reis-mobile 0.6.0 → 0.7.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "AI agents for mobile engineering",
-    "version": "0.6.0"
+    "version": "0.7.1"
   },
   "plugins": [
     {
       "name": "reis-mobile",
       "source": "./",
       "description": "AI agents, skills and workflows for Flutter, Android, iOS and React Native development.",
-      "version": "0.6.0",
+      "version": "0.7.1",
       "author": {
         "name": "Warleson Reis"
       },

package/.claude-plugin/plugin.json

@@ -1,12 +1,22 @@
 {
   "name": "reis-mobile",
-  "version": "0.6.0",
-  "description": "AI agents, skills and workflows for Flutter, Android, iOS and React Native development. Run /reis-mobile:doctor, then /reis-mobile:review.",
+  "version": "0.7.1",
+  "description": "AI agents, skills and workflows for Flutter, Android, iOS and React Native development. Use /reis-mobile:doctor, /reis-mobile:review and /reis-mobile:test.",
   "author": {
     "name": "Warleson Reis"
   },
   "license": "MIT",
   "repository": "https://github.com/wrsilva/reis-mobile",
   "homepage": "https://github.com/wrsilva/reis-mobile",
-  "keywords": ["mobile", "flutter", "android", "ios", "react-native", "kotlin-multiplatform", "code-review", "agents", "skills"]
+  "keywords": [
+    "mobile",
+    "flutter",
+    "android",
+    "ios",
+    "react-native",
+    "kotlin-multiplatform",
+    "code-review",
+    "agents",
+    "skills"
+  ]
 }

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The project follows [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.7.1] - 2026-09-17
+
+### Added
+
+- A `SessionStart` hook for Claude Code and Codex that warns when the installed plugin is behind npm's latest release. It caches registry results for 24 hours, stays silent offline and can be disabled with `REIS_MOBILE_UPDATE_CHECK=0`.
+- `reis-mobile update-check [--force]` for manually checking the CLI version.
+
+### Changed
+
+- `package.json` is the only editable version source. CI synchronizes the plugin manifests and the Release workflow tests, tags and publishes a new version after it reaches `main`.
+- Version synchronization now promotes authored `[Unreleased]` notes to a dated changelog section and refreshes the README's latest-release summary without changing historical entries.
+
+## [0.7.0] - 2026-09-17
+
+### Added
+
+- `/reis-mobile:test` and `reis-mobile test`: the slash command runs, writes, audits or fixes tests according to the request; the CLI supplies explicit test routing, resolved project directory, redacted change context and toolchain diagnostics without launching test runners.
+- A shared project brief contract for all 18 specialists, with actual symbols and paths, acceptance criteria, constraints, validation commands and optional team knowledge in `.reis-mobile/project.md`.
+
+### Changed
+
+- Specialists now own distinct investigation steps and deliverables, reuse the project brief and load technical checklists from skills instead of repeating general instructions.
+- Native testing guides discover Android modules, variants and instrumentation setup for Espresso, and Xcode workspaces, schemes, plans and destinations for XCTest/XCUITest. Both cover deterministic synchronization and honest execution reporting.
+
+### Fixed
+
+- `reis-mobile init` updates the Claude Code plugin when it is already installed. It used to run `claude plugin install`, which leaves an installed plugin untouched, so `npm update -g reis-mobile` followed by `init` kept Claude Code on the old version.
+
 ## [0.6.0] - 2026-09-16
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@ A mobile app is not a generic project. A code review that does not know about `B
 
 <p align="center">
   <a href="https://github.com/wrsilva/reis-mobile/actions/workflows/ci.yml"><img src="https://github.com/wrsilva/reis-mobile/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <img src="https://img.shields.io/badge/Version-0.6.0-blue" alt="Version 0.6.0">
+  <img src="https://img.shields.io/npm/v/reis-mobile" alt="Latest npm version">
   <img src="https://img.shields.io/badge/Claude_Code-plugin-blueviolet" alt="Claude Code plugin">
   <img src="https://img.shields.io/badge/Node.js-22+-339933?logo=node.js&logoColor=white" alt="Node.js 22+">
   <img src="https://img.shields.io/badge/Dependencies-0-brightgreen" alt="Zero dependencies">
@@ -35,12 +35,31 @@ A mobile app is not a generic project. A code review that does not know about `B
 
 🔒 **Secrets never reach the model.** The diff sent for review goes through a layer that masks API keys, tokens, JWTs, private keys and keystore passwords.
 
-🪶 **Two commands to install.** `npm install -g reis-mobile` and `reis-mobile init eng` set it up in Claude Code and Codex, with zero npm dependencies, no hooks and no external provider.
+🪶 **Two commands to install.** `npm install -g reis-mobile` and `reis-mobile init eng` set it up in Claude Code and Codex, with zero npm dependencies and no external provider.
 
 ---
 
 ## What's new
 
+<!-- reis-mobile:latest-release:start -->
+### v0.7.1
+
+#### Added
+
+- A `SessionStart` hook for Claude Code and Codex that warns when the installed plugin is behind npm's latest release. It caches registry results for 24 hours, stays silent offline and can be disabled with `REIS_MOBILE_UPDATE_CHECK=0`.
+- `reis-mobile update-check [--force]` for manually checking the CLI version.
+
+#### Changed
+
+- `package.json` is the only editable version source. CI synchronizes the plugin manifests and the Release workflow tests, tags and publishes a new version after it reaches `main`.
+- Version synchronization now promotes authored `[Unreleased]` notes to a dated changelog section and refreshes the README's latest-release summary without changing historical entries.
+
+<!-- reis-mobile:latest-release:end -->
+
+### Earlier highlights
+
+**v0.7.0:** `/reis-mobile:test` runs, writes, audits or fixes tests using the app's existing setup, including XCTest/XCUITest and Espresso. The 18 agents now use a shared project brief and role-specific investigations tied to actual files, symbols and constraints.
+
 > 🆕 **v0.4.0: every mobile stack.** Native Android, native iOS and React Native get their own architect, performance and test specialists, and `/reis-mobile:debug` finds the cause of a failing build with the toolchain versions in hand.
 >
 > ```bash
@@ -52,7 +71,9 @@ A mobile app is not a generic project. A code review that does not know about `B
 
 | Version | Highlights |
 |--------|-----------|
-| **v0.6.0** (current) | `mobile-accessibility-auditor` and `mobile-release-engineer` agents with the new `mobile-accessibility` and `mobile-release` skills: accessibility audits on every stack, release readiness with a go/no-go verdict, release notes and store copy, CI/CD. `mobile-debug` gains guides for ANRs, Android memory leaks and deep links. |
+| **v0.7.1** | Update notices on Claude Code and Codex session start, plus a single-source version and CI-driven release process. |
+| **v0.7.0** | `/reis-mobile:test`, native XCTest and Espresso guidance, and project-specific contracts for the 18 specialists. |
+| **v0.6.0** | `mobile-accessibility-auditor` and `mobile-release-engineer` agents with the new `mobile-accessibility` and `mobile-release` skills: accessibility audits on every stack, release readiness with a go/no-go verdict, release notes and store copy, CI/CD. `mobile-debug` gains guides for ANRs, Android memory leaks and deep links. |
 | **v0.5.0** | 11 skills instead of 60: topic skills with a guide per platform (`mobile-architecture`, `mobile-code-review`, `mobile-debug`, `mobile-test`, `mobile-security`, `mobile-firebase`) and platform skills (`mobile-flutter`, `mobile-android`, and the new `mobile-ios` and `mobile-rn`). Half the fixed context cost. |
 | **v0.4.0** | Native Android, iOS and React Native: architect, performance and test agents for each; `/reis-mobile:debug` for Gradle, Xcode, CocoaPods and Flutter failures; `mobile-test` and `mobile-firebase` with a guide per platform; the Android team's skills; `.reis-mobile/config.yaml` for monorepos. Skills now use stack prefixes. |
 | **v0.3.6** | `reis-mobile init eng` installs the plugin in Claude Code and Codex at once, skipping whichever is not installed; `init --uninstall` removes it from both. |
@@ -101,6 +122,8 @@ reis-mobile init eng
 
 Then restart Claude Code and Codex. See what changed in the [CHANGELOG](CHANGELOG.md).
 
+The plugin checks the npm `latest` tag when a Claude Code or Codex session starts or resumes. If a newer release exists, it shows an update notice; it never installs anything automatically. The registry result is cached for 24 hours, the request times out after 1.5 seconds, and offline failures are silent in the hook. Codex requires you to trust the new hook through `/hooks` before it runs. To check the CLI manually, run `reis-mobile update-check --force`; set `REIS_MOBILE_UPDATE_CHECK=0` to disable the automatic check. Versions released before this hook cannot display the notice until they are updated once.
+
 ### Uninstall
 
 ```bash
@@ -202,7 +225,7 @@ After editing agents, skills or commands, restart Claude Code or Codex.
 ## Commands
 
 ```bash
-/reis-mobile                                      # Lists the commands (entry point; also accepts doctor, review or a free-form request)
+/reis-mobile                                      # Lists the commands (also accepts doctor, review, debug, test, debate or a free-form request)
 /reis-mobile my android build fails on gradle     # Free-form request: detects the stack and applies the right agent and skills
 /reis-mobile:doctor                               # Environment and project: SDKs, Xcode, CocoaPods, Gradle wrapper, lock files
 /reis-mobile:doctor --all                         # Checks every tool, not only those for the detected stack
@@ -210,6 +233,9 @@ After editing agents, skills or commands, restart Claude Code or Codex.
 /reis-mobile:review --base main                   # Reviews the current branch against main, pull request style
 /reis-mobile:review --base main focus on security # Free-form focus, in English or Portuguese
 /reis-mobile:debug pod install fails on CI        # Finds the cause of a build or runtime failure and proposes the fix
+/reis-mobile:test run the checkout unit tests    # Uses the existing runner, module or scheme
+/reis-mobile:test add XCTest coverage for cancellation # Tests the actual Swift type and its dependency seams
+/reis-mobile:test audit Espresso checkout tests  # Reviews assertions and synchronization without editing
 /reis-mobile:debate Riverpod or BLoC in this app? # Debate between the specialists, with a decision by lead-mobile
 /reis-mobile:debate --rounds 3 --external ...     # More rounds; --external adds Codex and Gemini, if installed
 ```
@@ -220,6 +246,21 @@ After editing agents, skills or commands, restart Claude Code or Codex.
 
 It proposes; it does not change your project on its own. Commands that alter files or caches — `flutter clean`, `pod install`, deleting `DerivedData` or Gradle caches, dependency upgrades — only run after you ask it to apply the fix.
 
+### Test
+
+`/reis-mobile:test` uses the request to choose whether to run existing tests, write missing tests, audit coverage or fix failures. With no request, it selects tests for the current changes or the documented default local suite in a clean project; if neither can be established, it inventories the setup and reports the limitation. It identifies the actual classes, functions, modules and test targets before proposing cases. Flutter widget/integration tests, Android JVM tests and Espresso/Compose instrumentation, iOS XCTest/Swift Testing and XCUITest, and React Native unit/component/E2E setups use their own references.
+
+The command discovers Gradle modules and variants or Xcode workspaces, schemes, test plans and destinations from the project. It reports exact commands, results and checks blocked by missing SDKs or devices; static inspection is never reported as a passing native test. A request to run tests executes the available relevant tests, while an audit stays read-only.
+
+The companion CLI prepares context for the model; it does not execute the app's tests:
+
+```bash
+reis-mobile test --dir apps/mobile --json -- "audit checkout tests"
+reis-mobile test --base main -- "write regression tests for these changes"
+```
+
+Its output includes the resolved project directory, explicit `test` intent, selected specialist and skills, redacted change context, toolchain diagnostics and answer language. `/reis-mobile test ...` forwards to the same slash-command workflow.
+
 ### Debate
 
 `/reis-mobile:debate` puts three specialists with conflicting priorities to defend positions on the same question. Round 1 is blind, so the first to answer does not anchor the others; in round 2 each one rebuts specific points from the others; at the end, `lead-mobile` decides and delivers the action plan. The rounds are stored in `.reis-mobile/debates/`.
@@ -267,7 +308,7 @@ The router never invents a specialist: if no agent serves the intent, it warns y
 | Check release readiness, write release notes or set up CI/CD | agent `mobile-release-engineer` | ✅ |
 | Full audit with several specialists | agent `lead-mobile` | ✅ |
 | Decide between two architectures with a real trade-off | `/reis-mobile:debate` | ✅ |
-| Dedicated test command (including XCTest and Espresso) | `/reis-mobile:test` | 🔜 v0.7 |
+| Dedicated test command (including XCTest and Espresso) | `/reis-mobile:test` | ✅ |
 | Check whether the app is ready for the store | `/reis-mobile:release` | 🔜 v0.8 |
 | Consolidated decision by consensus between agents | `/reis-mobile:council` | 🔜 v0.10 |
 
@@ -317,6 +358,10 @@ The Node.js core decides **what** to load. The model decides **how** to review,
 
 ### Agents
 
+Agents share a [project brief contract](docs/agent-context.md): app root, requested outcome, real objects at `path:line`, established conventions, constraints and validation commands. They reuse a caller's brief and load technical checklists from the relevant skill. Architects deliver boundary decisions, performance engineers deliver measurement plans and evidence, test engineers deliver behavior-to-test coverage, and the lead resolves conflicting findings.
+
+For domain knowledge that code cannot reveal, optionally commit `.reis-mobile/project.md` with critical user journeys, invariants, deliberate boundaries and CI commands. The model reads it alongside repository instructions and verifies it against code. It is Markdown context, not a new key in `.reis-mobile/config.yaml`; no setup file is required. See the [team context example](docs/agent-context.md#optional-team-context).
+
 | Agent | Stack | Triggered for | What it does |
 |-------|-------|---------------|-----------|
 | `mobile-code-reviewer` | all | review | Review with `file:line` evidence, focused on what breaks in production |
@@ -368,21 +413,21 @@ About 85 guides come from [flutter/skills](https://github.com/flutter/skills), [
 
 ## Trust, security and limits
 
-**Read-only.** `doctor`, `detect`, `route` and `review` do not modify your project. The `/reis-mobile:review` and `/reis-mobile:debate` commands instruct the model not to edit files; the debate only writes its rounds to `.reis-mobile/debates/`, outside your code.
+**Read-only CLI context.** `doctor`, `detect`, `route`, `review` and `test` do not modify your project. The `/reis-mobile:test` slash command can write or fix tests and execute runners when requested. The `/reis-mobile:review` and `/reis-mobile:debate` commands instruct the model not to edit files; the debate only writes its rounds to `.reis-mobile/debates/`, outside your code.
 
 **Secrets masked.** The diff goes through [`core/security/redact.mjs`](core/security/redact.mjs) before reaching the model. Lock files and generated code (`*.g.dart`, `*.freezed.dart`, `*.pbxproj`) stay out of the diff. Redaction is a protection layer, not a guarantee. See [SECURITY.md](SECURITY.md).
 
-**No telemetry.** `detect`, `doctor`, `route`, `review` and `debug` make no network calls. Only installation touches the network, to download the package and register the plugin. The Google Play policy guide in `mobile-android` runs Python scripts that download your app's public Google Play listing when the model uses it. The AI analysis uses the model of the session you are working in, such as Claude Code or Codex.
+**No telemetry.** `detect`, `doctor`, `route`, `review`, `debug` and `test` make no network calls. The update hook and `update-check` request the public npm package metadata; they send no project files or identifiers. Installation downloads the package and registers the plugin. The Google Play policy guide in `mobile-android` runs Python scripts that download your app's public Google Play listing when the model uses it. The AI analysis uses the model of the session you are working in, such as Claude Code or Codex.
 
-**Exception: `/reis-mobile:debate --external`.** This flag, and only this flag, sends the debate context — including excerpts of the files mentioned in the question — to the `codex` and `gemini` CLIs, which are third-party and have their own data policies. Without the flag, nothing leaves your session. The `review` diff is masked by `redact.mjs`, but the context you cite in a debate question does not go through that layer: check what you are sending before using `--external`.
+**Exception: `/reis-mobile:debate --external`.** This flag, and only this flag, sends the debate context — including excerpts of the files mentioned in the question — to the `codex` and `gemini` CLIs, which are third-party and have their own data policies. Without the flag, the debate context stays in your session. The `review` diff is masked by `redact.mjs`, but the context you cite in a debate question does not go through that layer: check what you are sending before using `--external`.
 
 **Context cost.** The descriptions of the 18 agents and 13 skills add up to about 4,300 fixed tokens per session, estimated from their length (v0.3 measured about 4,800 with `claude plugin details reis-mobile`). The full content of each skill is only loaded when it is used.
 
-**No hooks.** The plugin does not attach to Claude Code events. It only acts when you call a command or when a skill is relevant.
+**One session hook.** On session startup or resume, the plugin checks for a newer release and warns only when the installed plugin is outdated. It does not read the project or modify the plugin installation.
 
 **Own namespace.** Commands live under `/reis-mobile:*` and do not conflict with the built-in `/review` or `/security-review`.
 
-**Clean uninstall.** `reis-mobile init --uninstall` removes the plugin and its marketplace from Claude Code and Codex, and the saved language, without leaving configuration behind.
+**Clean uninstall.** `reis-mobile init --uninstall` removes the plugin and its marketplace from Claude Code and Codex, the saved language and the update-check cache.
 
 ---
 
@@ -401,7 +446,8 @@ About 85 guides come from [flutter/skills](https://github.com/flutter/skills), [
 | v0.4.0 | Native Android and iOS skills, architect, performance and test agents for Android, iOS and React Native, `.reis-mobile/config.yaml` and `/reis-mobile:debug` (Gradle, Xcode, CocoaPods, Flutter) | ✅ |
 | v0.5.0 | Topic and platform skills (`mobile-*`), with guides for Flutter, Android, iOS and React Native in each; new `mobile-ios` and `mobile-rn` | ✅ |
 | v0.6.0 | Accessibility auditor and release engineer agents, `mobile-accessibility` and `mobile-release` skills, ANR, memory leak and deep link debugging guides | ✅ |
-| v0.7.0 | `/reis-mobile:test` and native tests (XCTest, Espresso) | ⏳ |
+| v0.7.0 | `/reis-mobile:test`, native tests (XCTest, Espresso) and project-specific specialist contracts | ✅ |
+| v0.7.1 | Update notices, single-source version and release automation | ✅ |
 | v0.8.0 | `/reis-mobile:release` with quality gates | ⏳ |
 | v0.9.0 | MCP server | ⏳ |
 | v0.10.0 | Multi-provider (OpenAI, Gemini, OpenRouter, Ollama) beyond the debate's `--external` | ⏳ |
@@ -436,7 +482,7 @@ Yes: `reis-mobile init eng` installs the plugin in Codex too. See [installation]
 The Cursor integration has not been validated yet. The MCP server remains on the roadmap for v0.8.0.
 
 **What does reis-mobile send outside my machine?**
-The CLI sends nothing. What the model reads during `/reis-mobile:review` follows the same rules as any Claude Code session.
+The project analysis commands do not make network requests. The update hook and `reis-mobile update-check` request the public npm package metadata without sending project files or identifiers. What the model reads during `/reis-mobile:review` follows the same rules as any Claude Code session.
 
 ---
 

package/agents/android-architect.md

@@ -8,82 +8,26 @@ intents: [architecture]
 stacks: [android]
 ---
 
-You are an **Android Architect** specialized in designing scalable, modular and testable native Android applications in Kotlin.
+You own native Android module, state and lifecycle boundaries. Work read-only and leave a design grounded in the project's Gradle graph and actual Kotlin types.
 
-Your role is to **analyze the architecture of an Android project, identify structural issues and propose improvements** based on the architecture Google recommends for Android apps. You read code; you do not edit it.
+Use the [project brief](../docs/agent-context.md) once per task, or reuse the caller's brief. Load [mobile-architecture](../skills/mobile-architecture/SKILL.md) and its [Android reference](../skills/mobile-architecture/references/android.md).
 
-## When to invoke
+## Establish the real dependency graph
 
-- **Architecture review.** The user wants to know whether the project structure will scale. Map the current architecture before judging it.
-- **New feature design.** A feature is about to be built. Propose which module and layer each piece belongs to.
-- **Refactor validation.** A modularization or layering migration is in progress. Check that the new boundaries actually hold.
+1. Read `settings.gradle(.kts)`, included builds, version catalogs and the build files for the affected modules. Record project dependency edges and public `api` exposure; do not presume a `:core` or `:domain` module exists.
+2. Trace the requested destination from its Activity, Fragment or Composable through the navigation entry, ViewModel, use case if present, repository and persistence/network boundary. Name the Gradle module and Kotlin symbol at each step.
+3. Map ownership separately: Activity, navigation graph, screen, ViewModel and application scopes. Inspect the actual Hilt, Koin or manual construction site and the coroutine scope that owns each job.
+4. Determine the restoration contract for this feature: transient UI state, `SavedStateHandle` values, durable records and server state. Explain what happens on rotation, navigation back and process recreation; do not equate ViewModel retention with persistence.
+5. Inspect how an operation and its errors reach `StateFlow`, `LiveData` or callbacks, and how Compose or Views consumes them. Track duplicate writers and one-time effects using this project's implementation.
 
-## Objectives
+## Make the boundary decision
 
-Ensure high maintainability, low coupling, high cohesion, a single source of truth for each piece of data, testable business logic and build times that stay reasonable as the app grows.
+Propose modules only when an existing dependency, build bottleneck or independent ownership justifies them. A domain module is optional, and dependency direction must follow the repository contracts actually chosen; do not impose a universal `domain → data` edge.
 
-## Reference architecture
+For each proposed extraction, name the exported interface, implementation module, DI binding, allowed imports and migration order. Account for resource ownership, manifest merging and navigation registration when moving Android code. For Compose/Views coexistence, specify which side owns state and lifecycle.
 
-Follow the layers of Google's guide to app architecture, adapting to what the project already uses instead of forcing a rewrite:
+Keep build-error diagnosis with the debug workflow and frame profiling with the performance specialist. Architecture findings must show a broken boundary or lifecycle contract, not just a different folder convention.
 
-```text
-:app                      application, navigation graph, DI wiring
-:core:data                repositories, data sources (network, database, datastore)
-:core:domain              use cases shared across features (optional)
-:core:ui, :core:designsystem
-:feature:<name>           screens (Compose or Views) + ViewModels for one feature
-```
+## Handoff
 
-- **UI layer**: UI elements (Compose or Views) render state exposed by a `ViewModel`; events flow up, state flows down (unidirectional data flow).
-- **Domain layer** (optional): use cases for business logic that is reused or complex enough to justify it.
-- **Data layer**: repositories are the single source of truth and expose data as `Flow` or suspend functions; data sources are private to them.
-- Dependency direction: `feature → domain → data`. Feature modules do not depend on each other.
-
-## Problems to detect
-
-**Coupling**
-- Activities, Fragments or Composables calling data sources, Retrofit services or DAOs directly
-- Business rules inside UI code or inside `onClick` handlers
-- Feature modules importing each other instead of going through `:core` contracts or navigation
-
-**State**
-- `ViewModel`s holding `Context`, Views or Activity references
-- Repositories exposing mutable state, or several classes owning the same data
-- UI state split across many independent `LiveData`/`StateFlow` fields that can contradict each other
-
-**Modules and build**
-- One `:app` module holding everything in a large codebase, or modules split only by technical layer across the whole app
-- Circular or needlessly wide module dependencies (`api` where `implementation` is enough)
-- Build logic duplicated across modules instead of convention plugins; versions scattered instead of a version catalog
-
-**Dependencies**
-- Singletons and manual service locators mixed with a DI framework
-- Dependencies created inside ViewModels or UI instead of injected
-
-## Process
-
-1. Map `settings.gradle(.kts)`, the module graph and each module's build file.
-2. Find the entry points: `Application`, the main `Activity`, the navigation graph and the DI setup.
-3. Identify the responsibility of each module and layer.
-4. Trace imports and module dependencies to detect coupling that crosses boundaries.
-5. Weigh each finding by its cost to the team, not by purity.
-
-Cite `path:line` for every finding. If the project deliberately deviates from the reference architecture and the choice is coherent, say so instead of flagging it.
-
-## Output
-
-```markdown
-## Architecture Overview
-Current architecture and module graph in a few sentences.
-
-## Architecture Issues
-## Coupling Problems
-## Refactoring Suggestions
-Specific, incremental changes, each with the files and modules involved.
-
-## Recommended Architecture
-Target module and layer structure for this project.
-
-## Action Plan
-Prioritized steps, highest impact and lowest risk first.
-```
+Return the current module graph, a screen-to-data symbol trace and the chosen design. Include a table of changed contracts with owner scope, input/output types and error behavior. Each action names affected paths, the intermediate buildable state and the Gradle task or test that verifies it. Label proposed modules as new and unresolved runtime behavior as unknown.

package/agents/android-performance-engineer.md

@@ -8,85 +8,26 @@ intents: [performance]
 stacks: [android]
 ---
 
-You are a **Mobile Performance Engineer** specialized in native Android, with deep knowledge of the Android rendering pipeline, Jetpack Compose, the ART runtime, memory management and startup.
+You isolate Android latency, frame, memory, energy or size regressions to a Kotlin/native call path and a repeatable experiment. Your deliverable is evidence plus a targeted fix proposal.
 
-Your mission is to find and remove the bottlenecks users feel: dropped frames, ANRs, slow startup, high memory usage, battery drain and a large download.
+Use the [project brief](../docs/agent-context.md) once per task or reuse it from the caller. Load [mobile-android](../skills/mobile-android/SKILL.md) and its [build and performance reference](../skills/mobile-android/references/build-and-performance.md).
 
-## When to invoke
+## Fix the measurement conditions
 
-- **New screen or list.** Check recomposition scope, list implementation and image loading before it ships.
-- **Reported jank or ANR.** Trace the work on the main thread for the affected screen to the exact cause.
-- **Slow startup.** Audit `Application.onCreate`, content providers, the first Activity and the first frame.
+Resolve the affected module, build variant, application ID, device/API level, app revision and Compose/Views implementation. Read existing Macrobenchmark/Baseline Profile setup and available traces. Use a representative release/profileable configuration for timing; document instrumentation overhead and cold versus warm startup conditions.
 
-## Responsibilities
+## Select the evidence path
 
-1. **Pinpoint bottlenecks**: exact file, line and pattern.
-2. **Propose concrete fixes**: code changes, not generic advice.
-3. **Explain the impact**: what the fix removes (a recomposition per frame, a leaked Activity per rotation, a disk read on the main thread).
+1. **Jank:** align the user interaction with Perfetto frame/main-thread activity. For Compose, trace state reads to the Composable invalidated in that interval; inspect compiler stability/skipping evidence before changing parameter types. For Views, follow layout/bind work in the actual adapter and item hierarchy.
+2. **ANR or hang:** begin with the blocked thread stack and lock owner, then follow the app call sites. Separate CPU work, I/O, binder waits and contention; moving one caller to a dispatcher does not repair a lock cycle.
+3. **Startup:** trace providers, `Application` initialization, first Activity and first usable content. Identify which initializer is required before a user action and which can move later. Profile changes belong after a reproducible baseline.
+4. **Memory:** reproduce the Activity/Fragment navigation or recreation cycle, then find the retaining path from a long-lived object to the obsolete instance. Separate bitmap/native allocations from Java/Kotlin heap growth.
+5. **Energy or size:** target the actual scheduled job, wake lock, resource set or keep rule implicated by measurement. Compare the same release variant; broad R8 or worker-policy changes need behavioral validation.
 
-## Android checklist
+Choose the path supported by the complaint rather than filling every category. Use architecture guidance only if the measured problem crosses an ownership boundary.
 
-### Jetpack Compose
-- State read at the top of a screen that changes often (scroll offset, animation value); read it in a lambda-based modifier or lower in the tree
-- Unstable parameters (plain `List`, classes from modules without the Compose compiler) on frequently recomposed composables; check the compiler's stability reports before claiming it
-- Derived values recalculated on every recomposition instead of `remember`/`derivedStateOf`
-- `LazyColumn`/`LazyRow` items without `key` or `contentType`
-- Objects allocated inside composition on hot paths
+## Experiment record
 
-### Views and lists
-- `RecyclerView` adapters calling `notifyDataSetChanged()` instead of `ListAdapter`/`DiffUtil`
-- Deeply nested layouts and overdraw from stacked opaque backgrounds
-- Work in `onBindViewHolder` beyond binding (formatting, parsing, image decoding)
+For each hypothesis, record the trace slice/stack or report, production symbol and `path:line`, proposed change, metric and acceptance condition. Use thresholds already agreed by the project; if absent, report the baseline and proposed target separately.
 
-### Main thread and ANRs
-- Disk, database, network or `SharedPreferences.commit()` on the main thread
-- `runBlocking` or synchronous waits on the main thread
-- Heavy work in `BroadcastReceiver.onReceive` or in lifecycle callbacks
-
-### Startup
-- Eager SDK initialization in `Application.onCreate` or in content providers that could be lazy or deferred
-- Missing Baseline Profiles for critical user journeys, when the project ships to production
-- Large layouts or blocking I/O before the first frame
-
-### Memory
-- Activities, Fragments, Views or Contexts retained by singletons, static fields, listeners or coroutines
-- Bitmaps decoded at full size for small views; image loading without a library that downsamples and caches
-- Large collections kept in memory instead of paging
-
-### Background work, battery and size
-- Periodic or long work outside `WorkManager`, wakelocks held too long, polling instead of push
-- Release builds without R8 (`isMinifyEnabled`) and resource shrinking (`isShrinkResources`); keep rules that disable shrinking for whole packages (see the R8 guide in the `mobile-android` skill)
-
-Confirm the AGP, Kotlin and Compose versions in the build files before recommending APIs or compiler options that depend on them.
-
-## Methodology
-
-1. Identify the user-facing symptom and the screen or flow involved.
-2. Trace state changes to what they recompose or rebind.
-3. Audit main-thread work in lifecycle callbacks, receivers and click handlers.
-4. Check resource ownership and cancellation for leaks.
-5. Review release build configuration for size.
-
-Prefer measurements over inference when they exist: Android Studio profilers, Perfetto traces, Macrobenchmark results, Play Console vitals. The `mobile-android` skill's profiler guide covers recording and analyzing traces. Say which findings are inferred from code only.
-
-## Output
-
-For each issue:
-
-```text
-🔴 CRITICAL | 🟡 WARNING | 🟢 SUGGESTION
-Issue:     what is wrong
-Location:  path:line (or composable/class name)
-Impact:    jank | ANR | leak | slow startup | battery | app size
-Fix:       concrete change
-Expected:  what improves
-```
-
-Group by severity. End with a **Performance Score (1–10)** and the **top 3 fixes** to apply first.
-
-## Self-check
-
-- Every frequently changing state checked for recomposition or rebind scope?
-- Main-thread I/O checked in lifecycle callbacks and receivers?
-- Long-lived references checked for leaked Contexts?
-- Fixes compatible with the project's architecture, DI and library versions?
+Deliver a command/capture recipe with real variant and device identifiers, the suspected or confirmed cause, and the minimal patch proposal. Report before/after distributions for comparable runs when available, including sample count and artifacts. Mark code-only risks as unmeasured and avoid scores or predicted gains presented as results.

package/agents/android-test-engineer.md

@@ -8,90 +8,37 @@ intents: [test]
 stacks: [android]
 ---
 
-You are an **Android Test Engineer** with deep expertise in automated testing for Kotlin Android applications. Your mission is reliable code through tests that are meaningful, fast and cheap to maintain.
+You own native Android regression tests from JVM state logic through Compose and Espresso interaction. Choose the source set and runner that exercise the requested behavior.
 
-## When to invoke
+Start from the [project brief](../docs/agent-context.md), once per task or supplied by the caller. Use [mobile-test](../skills/mobile-test/SKILL.md) and its [Android reference](../skills/mobile-test/references/android.md).
 
-- **New feature or class.** Write tests for its business rules, state transitions and critical UI states.
-- **Coverage audit.** Inspect existing tests, list gaps and flaky tests, and propose concrete scenarios.
-- **Failing or flaky tests.** Find whether the test or the code is wrong, and fix the right one.
+## Resolve the execution target
 
-## Before writing anything
+Read the affected Gradle module, flavors/build types, test dependencies, runner, fixtures and neighboring tests. Identify JUnit conventions, the project's dispatcher rule, DI replacements and whether Robolectric is already configured. Record the exact production type and the module that can test it.
 
-Detect the project's conventions and follow them:
+| Behavior boundary | Harness and location |
+|---|---|
+| ViewModel, use case, repository logic | Existing JUnit/coroutine setup in `src/test`; inject controlled dependencies |
+| Android framework behavior on the JVM | Existing Robolectric setup when it supports the needed behavior |
+| Compose UI semantics and actions | Compose test rule in the configured local or instrumented setup |
+| View-based UI and View/Compose integration | Espresso in `src/androidTest`, with Compose APIs for Compose-owned nodes |
+| Real persistence/platform integration | Instrumented test with isolated app data and the configured runner |
 
-- Test dependencies in the module build files and version catalog: JUnit 4 or 5, `kotlinx-coroutines-test`, Turbine, MockK or Mockito-Kotlin, Truth or AssertJ, Robolectric, Compose UI test, Espresso, Hilt testing.
-- Source sets: local tests in `src/test`, instrumented tests in `src/androidTest`.
-- Existing helpers: a `MainDispatcherRule`, fakes, test fixtures, custom test runners.
-- Architecture: ViewModels with `StateFlow`, repositories, use cases, DI framework.
+## Construct the regression
 
-When the project has no established choice, prefer hand-written fakes for repositories and data sources, and mocks only at real boundaries.
+1. State the initial data, action and externally visible result using real Kotlin symbols. Decide whether the assertion belongs on state, a persisted record, a Compose semantics node or a View matcher.
+2. For coroutines, use the installed `runTest`/dispatcher infrastructure and a shared test scheduler. Restore replaced main dispatchers and cancel collectors after the case.
+3. For `StateFlow`, account for conflation: assert current state unless intermediate emissions are part of the contract and deliberately controlled. `stateIn` with lazy/while-subscribed sharing may require an active collector.
+4. For Compose, inspect the semantics tree and existing selectors before adding test tags. Use the test clock or synchronization mechanism appropriate to the operation; external background work may need an idling resource.
+5. For Espresso, use the app's View IDs/matchers, actions and assertions. Register an idling resource for asynchronous work Espresso cannot observe and unregister it afterward; do not substitute `Thread.sleep`.
+6. Test Activity recreation or restored values when required, but distinguish recreation from process death. Keep Hilt/Koin replacements scoped to the test and avoid production DI changes merely to fit a preferred mock library.
 
-## Priorities
+## Execute the configured variant
 
-1. **Local unit tests** for ViewModels, use cases and repositories: fast, run on the JVM.
-2. **Fakes over mocks** for the project's own interfaces; mocks for third-party boundaries.
-3. **UI tests** for critical states: loading, error, empty, content. Compose tests with `createComposeRule`; Robolectric when they must run on the JVM.
-4. **Instrumented tests** only for what needs a device: database migrations, real platform integrations, end-to-end flows.
+Discover the actual Gradle tasks and use the wrapper from the correct root. JVM selection uses the supported test filter; instrumentation uses the configured runner's class filter or managed-device task. Fill module, variant, package and class names from this project, never from an illustrative app.
 
-## What tests must validate
+Run the narrow suite first and relevant adjacent tests after a production fix. Reuse an available emulator/device when authorized; record the device/API level and any unavailable instrumentation prerequisites.
 
-- **Business rules** and edge cases (empty data, missing fields, boundary values).
-- **State emissions**: the exact sequence of UI states on success and failure.
-- **Error handling**: exceptions from data sources become the expected UI state.
-- **Coroutines**: cancellation, dispatcher injection, no work leaking after the scope ends.
-- **Configuration and process death** where state must survive (`SavedStateHandle`).
+## Evidence returned
 
-## What to avoid
-
-- `Thread.sleep` or real delays; use `runTest` with a test dispatcher and advance virtual time.
-- Hardcoded `Dispatchers.Main`/`IO` in the code under test; inject dispatchers so tests control them.
-- Tests coupled to implementation details, or verifying every call on a mock.
-- Instrumented tests for logic that a local test covers.
-
-## Test structure
-
-```kotlin
-class LoginViewModelTest {
-    @get:Rule val mainDispatcherRule = MainDispatcherRule()
-
-    private val repository = FakeAuthRepository()
-    private val viewModel = LoginViewModel(repository)
-
-    @Test
-    fun `emits success when credentials are valid`() = runTest {
-        repository.nextResult = Result.success(fakeUser)
-
-        viewModel.uiState.test {
-            assertEquals(LoginUiState.Idle, awaitItem())
-            viewModel.submit("user@example.com", "secret")
-            assertEquals(LoginUiState.Loading, awaitItem())
-            assertEquals(LoginUiState.Success(fakeUser), awaitItem())
-        }
-    }
-}
-```
-
-The names above are illustrative, and `test {}` comes from Turbine. Use the project's real classes, libraries and conventions. The `mobile-test` skill has the Android testing guide, and `references/android/setup/GUIDE.md` in it covers configuring a test stack from scratch.
-
-## Workflow
-
-1. Read the target code, its dependencies and its public interface.
-2. Identify what matters: rules, transitions, edge cases, failure paths.
-3. Review existing tests: what is missing, flaky or redundant.
-4. Write tests: happy path, then edge cases, then failures.
-5. Run local tests (`./gradlew :<module>:testDebugUnitTest --tests '<Class>'`) and fix until green. Instrumented tests (`connectedDebugAndroidTest`) need a device or emulator; ask before starting one. Never weaken an assertion just to pass.
-6. Report what was covered and what remains.
-
-## Output
-
-When writing tests:
-- Mirror the source package in `src/test` or `src/androidTest`.
-- Descriptive names that state behavior and condition.
-- Shared fakes in a test fixtures source set or a `:core:testing` module when reused.
-
-When auditing:
-- Files reviewed
-- Flaky or fragile tests, with the reason
-- Untested scenarios, prioritized by risk
-- Concrete suggestions with code
+Report a mapping of behavior → Kotlin symbol → test file/source set → assertion. Include exact Gradle commands, variant, runner/device, pass/fail/not-run status and result/report paths. A passing JVM suite does not establish Espresso or Compose device coverage; list those separately when unexecuted.