reis-mobile 0.3.6 → 0.5.0

package/bin/reis-mobile.mjs

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { LANGUAGES, configPath, removeConfig, resolveLanguage, saveLanguage } from '../core/config/language.mjs';
+import { resolveProjectDir } from '../core/config/project.mjs';
 import { collectReviewContext } from '../core/context/context-engine.mjs';
 import { detectStack } from '../core/detection/stack-detector.mjs';
 import { runDoctor } from '../core/diagnostics/doctor.mjs';
@@ -24,11 +25,12 @@ Commands:
   doctor                     Diagnose the environment for the detected stack
   route <prompt...>          Show which intent, agent and skills a prompt resolves to
   review [prompt...]         Route a code review and collect the git context for it
+  debug [problem...]         Route a build or runtime failure and report the toolchain it runs on
   agents | skills | stacks   List registered components
   validate                   Validate the plugin's agents, skills and stacks
 
 Options:
-  --dir <path>      Project directory (default: current directory)
+  --dir <path>      Project directory (default: current directory, or "app" in .reis-mobile/config.yaml)
   --intent <id>     Force an intent (${INTENT_IDS.join(', ')})
   --base <ref>      review: compare <ref>...HEAD instead of the working tree
   --all             doctor: check every tool, not only the relevant ones
@@ -63,6 +65,7 @@ const COMMANDS = {
   doctor: commandDoctor,
   route: commandRoute,
   review: commandReview,
+  debug: commandDebug,
   agents: (options) => commandList('agents', options),
   skills: (options) => commandList('skills', options),
   stacks: (options) => commandList('stacks', options),
@@ -88,9 +91,16 @@ async function main(argv) {
     console.error(`Unknown command "${name}".\n\n${USAGE}`);
     return 1;
   }
-  return (await command({ ...options, dir: options.dir ?? process.cwd(), prompt: rest.join(' ') })) ?? 0;
+  const dir = options.dir ?? process.cwd();
+  // Commands that analyze a project honor `app:` from .reis-mobile/config.yaml.
+  const project = PROJECT_COMMANDS.has(name) ? resolveProjectDir(dir) : { projectDir: dir, config: null, warnings: [] };
+  for (const warning of project.warnings) console.error(`! ${warning}`);
+
+  return (await command({ ...options, dir: project.projectDir, project, prompt: rest.join(' ') })) ?? 0;
 }
 
+const PROJECT_COMMANDS = new Set(['detect', 'doctor', 'route', 'review', 'debug']);
+
 async function commandInit({ local, scope, uninstall, lang, prompt }) {
   const requested = lang ?? (prompt || process.env.REIS_MOBILE_LANG || undefined);
   // Validate before touching Claude Code or Codex, so a typo does not leave a half-done install.
@@ -136,10 +146,12 @@ async function commandLang({ prompt, json }) {
   return 0;
 }
 
-async function commandDetect({ dir, json, lang }) {
+async function commandDetect({ dir, project, json, lang }) {
   const detection = await detectStack(dir);
   const language = await resolveLanguage({ flag: lang });
-  if (json) return print({ ...detection, language });
+  if (json) return print({ ...detection, language, projectConfig: project.config?.path ?? null });
+
+  printProject(project);
 
   console.log(`Stack       ${detection.stack}${detection.variant ? ` (${detection.variant})` : ''}`);
   console.log(`Languages   ${detection.languages.join(', ') || '-'}`);
@@ -151,47 +163,54 @@ async function commandDetect({ dir, json, lang }) {
   return detection.stack === 'unknown' ? 2 : 0;
 }
 
-async function commandDoctor({ dir, all, strict, json, lang }) {
+async function commandDoctor({ dir, project, all, strict, json, lang }) {
   const report = await runDoctor({ projectDir: dir, all });
   const language = await resolveLanguage({ flag: lang });
   if (json) {
-    print({ ...report, language });
+    print({ ...report, language, projectConfig: project.config?.path ?? null });
   } else {
     console.log('reis-mobile doctor\n');
-    for (const [section, title] of [['environment', 'Environment'], ['project', 'Project'], ['integrations', 'Integrations']]) {
-      const checks = report.checks.filter((check) => check.section === section);
-      if (!checks.length) continue;
-      console.log(`${title}\n${'-'.repeat(title.length)}`);
-      for (const check of checks) console.log(`${check.label.padEnd(16)}${SYMBOLS[check.status]} ${check.detail ?? ''}`.trimEnd());
-      console.log('');
-    }
+    printProject(project);
+    printDoctorChecks(report);
     console.log(report.warnings ? `${report.warnings} warning(s)` : 'No issues found');
     printLanguage(language);
   }
   return strict && report.warnings ? 1 : 0;
 }
 
+function printDoctorChecks(report) {
+  for (const [section, title] of [['environment', 'Environment'], ['project', 'Project'], ['integrations', 'Integrations']]) {
+    const checks = report.checks.filter((check) => check.section === section);
+    if (!checks.length) continue;
+    console.log(`${title}\n${'-'.repeat(title.length)}`);
+    for (const check of checks) console.log(`${check.label.padEnd(16)}${SYMBOLS[check.status]} ${check.detail ?? ''}`.trimEnd());
+    console.log('');
+  }
+}
+
 const SYMBOLS = { ok: '✓', warning: '✗', info: '-', skipped: '-' };
 
-async function commandRoute({ dir, intent, prompt, json, lang }) {
+async function commandRoute({ dir, project, intent, prompt, json, lang }) {
   if (!prompt && !intent) {
     console.error('route needs a prompt or --intent.');
     return 1;
   }
   const result = await route({ prompt, intent, projectDir: dir });
   const language = await resolveLanguage({ flag: lang });
-  if (json) return print({ ...summarizeRoute(result), language });
+  if (json) return print({ ...summarizeRoute(result), language, projectConfig: project.config?.path ?? null });
+  printProject(project);
   printRoute(result);
   printLanguage(language);
   return 0;
 }
 
-async function commandReview({ dir, base, prompt, json, lang }) {
+async function commandReview({ dir, project, base, prompt, json, lang }) {
   const result = await route({ prompt, intent: 'review', projectDir: dir });
   const context = collectReviewContext({ projectDir: dir, base });
   const language = await resolveLanguage({ flag: lang });
-  if (json) return print({ ...summarizeRoute(result), language, context });
+  if (json) return print({ ...summarizeRoute(result), language, projectConfig: project.config?.path ?? null, context });
 
+  printProject(project);
   printRoute(result);
   printLanguage(language);
   console.log(`\nContext     ${context.mode}${context.base ? ` (${context.base}...HEAD)` : ''}`);
@@ -201,6 +220,24 @@ async function commandReview({ dir, base, prompt, json, lang }) {
   return 0;
 }
 
+/**
+ * Routes a failure to the debug agent and skills, and adds the doctor report: most build
+ * failures are toolchain mismatches (JDK, Gradle, Xcode, CocoaPods), which the report shows.
+ */
+async function commandDebug({ dir, project, prompt, json, lang }) {
+  const result = await route({ prompt, intent: 'debug', projectDir: dir });
+  const doctor = await runDoctor({ projectDir: dir });
+  const language = await resolveLanguage({ flag: lang });
+  if (json) return print({ ...summarizeRoute(result), language, projectConfig: project.config?.path ?? null, doctor });
+
+  printProject(project);
+  printRoute(result);
+  printLanguage(language);
+  console.log('');
+  printDoctorChecks(doctor);
+  return 0;
+}
+
 async function commandList(kind, { json }) {
   const registry = await loadRegistry();
   const items = registry[kind];
@@ -243,6 +280,11 @@ function printRoute(result) {
   for (const warning of result.warnings) console.log(`! ${warning}`);
 }
 
+/** Only printed when .reis-mobile/config.yaml moved the command to another folder. */
+function printProject({ projectDir, config }) {
+  if (config?.data.app !== undefined) console.log(`Project     ${projectDir} (app from ${config.path})`);
+}
+
 /** `-` means no saved language: the commands follow the language of the request. */
 function printLanguage(language) {
   console.log(`Language    ${language ?? '-'}`);

package/commands/debate.md

@@ -39,6 +39,15 @@ Choose **three** agents whose priorities genuinely conflict on the question. A d
 | `reis-mobile:flutter-architect` | Layer boundaries, modularization, long-term maintenance cost | `opus` |
 | `reis-mobile:flutter-performance-engineer` | Frames, rebuilds, memory, startup time — hostile to indirection | `sonnet` |
 | `reis-mobile:flutter-test-engineer` | Testability, injection seams, coverage cost | `sonnet` |
+| `reis-mobile:android-architect` | Native Android layers, Gradle modularization, long-term maintenance cost | `opus` |
+| `reis-mobile:android-performance-engineer` | Recomposition, ANRs, startup, memory — hostile to indirection | `sonnet` |
+| `reis-mobile:android-test-engineer` | Testability, injected dispatchers and fakes, coverage cost | `sonnet` |
+| `reis-mobile:ios-architect` | Native iOS structure, packages, concurrency isolation | `opus` |
+| `reis-mobile:ios-performance-engineer` | Hangs, view updates, launch time, retain cycles | `sonnet` |
+| `reis-mobile:ios-test-engineer` | Testability, protocol seams, coverage cost | `sonnet` |
+| `reis-mobile:rn-architect` | Feature boundaries, server vs client state, native module isolation | `opus` |
+| `reis-mobile:rn-performance-engineer` | Re-renders, lists, JavaScript thread, startup | `sonnet` |
+| `reis-mobile:rn-test-engineer` | Testability through the UI, mocks at boundaries, coverage cost | `sonnet` |
 | `reis-mobile:plugin-native-expert` | Flutter–native boundary, platform channels, lifecycle | `opus` |
 | `reis-mobile:mobile-staff-engineer` | Build, release, migration, cross-platform trade-offs | `opus` |
 | `reis-mobile:mobile-code-reviewer` | Concrete risk in the code that already exists | `sonnet` |
@@ -49,7 +58,7 @@ Automatic selection must end with **at least two different models** among the pa
 
 Selection rules:
 
-- The detected stack rules. The `flutter-*` agents only join Flutter projects; in native Android or iOS, use `mobile-staff-engineer` and `mobile-code-reviewer`.
+- The detected stack rules. The `flutter-*` agents only join Flutter projects, `android-*` native Android, `ios-*` native iOS and `rn-*` React Native. Pick the architect, performance and test specialists of the detected stack first; `mobile-staff-engineer` and `mobile-code-reviewer` fit any stack.
 - Without native code in the project, do not call `plugin-native-expert`.
 - `--agents` overrides the automatic choice, but not the models: each agent keeps the one from the table. Unknown name: warn and stop.
 - `reis-mobile:lead-mobile` never debates — it moderates in step 7, always on `opus`, because synthesizing conflicting positions is the heaviest work in the flow.

package/commands/debug.md

@@ -0,0 +1,60 @@
+---
+description: Mobile debugging — routes a build or runtime failure (Gradle, Xcode, CocoaPods, Flutter) to the right agent and skills, finds the cause with evidence and proposes the fix
+argument-hint: "<error message, failing command or description of the problem>"
+allowed-tools: ["Bash(node:*)", "Bash(git:*)", "Bash(flutter:*)", "Bash(dart:*)", "Bash(./gradlew:*)", "Bash(xcodebuild:*)", "Bash(pod:*)", "Bash(java:*)", "Read", "Grep", "Glob"]
+---
+
+# reis-mobile debug
+
+Arguments received: `$ARGUMENTS`
+
+The arguments are the problem: an error message, the command that fails, or a description. Without them, ask the user for the failing command and its full output, and stop. A debug session without the actual error guesses; one with it verifies.
+
+## 1. Route and gather the toolchain
+
+Run via Bash, with correct quoting:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/reis-mobile.mjs" debug --dir "$PWD" -- "<problem>"
+```
+
+The output reports:
+
+- `Project`, when `.reis-mobile/config.yaml` points the command at an app folder;
+- `Intent`, `Stack`, `focus` and `area` (`gradle`, `xcode`, `cocoapods`, `signing`, `pub`...);
+- `Agent` and `Skills`, in priority order;
+- `Language`, the language to answer in (see **Language**);
+- the doctor checks: installed tools and their versions, lock files, Gradle wrapper, iOS deployment target.
+
+If the command fails, show the error to the user and stop.
+
+## Language
+
+The CLI output has a `Language` line. Write everything the user reads in that language: `en` is English, `pt` is Brazilian Portuguese. With `-`, use the language of the user's request. Code, identifiers, file paths, commands and quoted tool output stay as they are.
+
+## 2. Load the instructions
+
+Read with the Read tool, in this order:
+
+1. `${CLAUDE_PLUGIN_ROOT}/agents/<Agent>.md`;
+2. `${CLAUDE_PLUGIN_ROOT}/skills/<skill>/SKILL.md` for each listed skill. `mobile-debug` maps the stack and the `area` from step 1 to its platform references; read the reference for each layer the failure crosses (a Flutter build that fails inside Gradle needs the Flutter and the Android references).
+
+## 3. Diagnose
+
+Follow the agent's process and the skills' checklists:
+
+1. **Find the first real error.** Build logs bury it under cascading failures. Quote the line that starts the failure, not the last `BUILD FAILED`.
+2. **Read the files that decide the behavior** before forming a theory: build scripts, wrapper and lock files, manifests, `Info.plist`, `Podfile`, project settings. Compare versions against the doctor output — a mismatch between the JDK, Gradle, AGP, Kotlin, Xcode or CocoaPods is the most common cause.
+3. **Reproduce when it is safe.** Read-only commands can run: `./gradlew --version`, `flutter --version`, `pod --version`, `xcodebuild -version`, `./gradlew :app:dependencies`. A build that only compiles (`./gradlew assembleDebug`, `flutter build apk --debug`) can run if the user already ran it or agrees, since it takes time and writes build outputs.
+4. **Confirm the cause** with evidence at `file:line` or in the log. If two causes are plausible, say which evidence would separate them instead of picking one.
+
+## 4. Propose, then wait
+
+Answer with:
+
+- **Cause:** one or two sentences, with the evidence.
+- **Fix:** the minimal change, as a diff or the exact commands, in the order to apply them.
+- **Why it works**, and what it changes beyond the error (a Gradle or Kotlin upgrade, a new minimum iOS version).
+- **How to verify:** the command that failed, run again.
+
+Do not edit files or run commands that change the project or the machine — `flutter clean`, `pod install`, `pod repo update`, deleting `DerivedData` or `~/.gradle` caches, dependency upgrades — until the user asks you to apply the fix. Once they do, apply it, run the verification command and report the result.

package/commands/reis-mobile.md

@@ -1,6 +1,6 @@
 ---
-description: reis-mobile entry point — lists the commands or forwards to doctor, review, debate or the right agent from a free-form request
-argument-hint: "[doctor | review | debate | free-form request]"
+description: reis-mobile entry point — lists the commands or forwards to doctor, review, debug, debate or the right agent from a free-form request
+argument-hint: "[doctor | review | debug | debate | free-form request]"
 allowed-tools: ["Bash(node:*)", "Bash(git:*)", "Read", "Grep", "Glob"]
 ---
 
@@ -21,6 +21,7 @@ Reply only with this list. The only thing to run is `node "${CLAUDE_PLUGIN_ROOT}
 ```text
 /reis-mobile:doctor                  Environment and project: SDKs, Xcode, CocoaPods, Gradle wrapper, lock files
 /reis-mobile:review [--base <ref>]   Code review of the changes (or the whole project)
+/reis-mobile:debug <problem>         Finds the cause of a build or runtime failure and proposes the fix
 /reis-mobile:debate <question>       Debate between the specialists, with a decision by lead-mobile
 /reis-mobile <free-form request>     Forwards the request to the agent and skills for the detected stack
 ```
@@ -36,6 +37,10 @@ When the language is `pt`, translate the descriptions and keep the commands as t
 
 Read `${CLAUDE_PLUGIN_ROOT}/commands/review.md` and follow all of it, treating the rest of the arguments (without the word `review`) as `$ARGUMENTS`.
 
+## `debug <problem>`
+
+Read `${CLAUDE_PLUGIN_ROOT}/commands/debug.md` and follow all of it, treating the rest of the arguments (without the word `debug`) as `$ARGUMENTS`.
+
 ## `debate [options] <question>`
 
 Read `${CLAUDE_PLUGIN_ROOT}/commands/debate.md` and follow all of it, treating the rest of the arguments (without the word `debate`) as `$ARGUMENTS`.

package/core/config/project.mjs

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+import { parseYamlSubset } from '../registry/frontmatter.mjs';
+
+export const PROJECT_CONFIG = join('.reis-mobile', 'config.yaml');
+
+const KNOWN_KEYS = new Set(['app']);
+
+/**
+ * Finds the nearest `.reis-mobile/config.yaml`, starting at `dir` and walking up, so a
+ * command run anywhere inside a monorepo sees the same settings.
+ *
+ * @returns {{ path: string, root: string, data: object } | null}
+ */
+export function findProjectConfig(dir) {
+  let current = resolve(dir);
+  for (;;) {
+    const path = join(current, PROJECT_CONFIG);
+    if (existsSync(path)) return { path, root: current, data: parseYamlSubset(readFileSync(path, 'utf8')) };
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * The directory commands should analyze. `app: apps/mobile` points a monorepo at its
+ * mobile app, relative to the folder that holds `.reis-mobile/`. A `dir` already inside
+ * the app is kept, so running from `apps/mobile/lib` still works.
+ *
+ * @returns {{ projectDir: string, config: object|null, warnings: string[] }}
+ */
+export function resolveProjectDir(dir) {
+  const requested = resolve(dir);
+  const config = findProjectConfig(requested);
+  if (!config) return { projectDir: requested, config: null, warnings: [] };
+
+  const warnings = Object.keys(config.data)
+    .filter((key) => !KNOWN_KEYS.has(key))
+    .map((key) => `${config.path}: unknown key "${key}" ignored`);
+
+  const { app } = config.data;
+  if (app === undefined) return { projectDir: requested, config, warnings };
+  if (typeof app !== 'string' || !app.trim() || isAbsolute(app)) {
+    throw new Error(`${config.path}: "app" must be a folder relative to ${config.root}, such as "apps/mobile"`);
+  }
+
+  const appDir = resolve(config.root, app);
+  if (!existsSync(appDir) || !statSync(appDir).isDirectory()) {
+    throw new Error(`${config.path}: app folder "${app}" does not exist`);
+  }
+  return { projectDir: isInside(requested, appDir) ? requested : appDir, config, warnings };
+}
+
+function isInside(child, parent) {
+  const path = relative(parent, child);
+  return path === '' || (!path.startsWith('..') && !isAbsolute(path));
+}

package/core/registry/frontmatter.mjs

@@ -1,9 +1,10 @@
 // Minimal YAML frontmatter parser, dependency-free on purpose: the plugin must run
 // straight from the Claude Code plugin cache without `npm install`.
 //
-// Supported subset: `key: scalar`, `key: [a, b]`, block lists (`key:` followed by
-// `  - item` lines) and block scalars (`key: |`, `|-`, `>`, `>-`). Nested maps, such as
-// the `metadata:` block of upstream skills, are skipped.
+// Supported subset: `key: scalar` (continued on indented lines, as YAML folds plain
+// scalars), `key: [a, b]`, block lists (`key:` followed by `  - item` lines) and block
+// scalars (`key: |`, `|-`, `>`, `>-`). Nested maps, such as the `metadata:` block of
+// upstream skills, are skipped.
 
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)([\s\S]*)$/;
 const BLOCK_SCALAR = /^([|>])([+-]?)$/;
@@ -14,10 +15,12 @@ export function parseFrontmatter(source) {
   return { data: parseYamlSubset(match[1]), body: match[2] };
 }
 
-function parseYamlSubset(text) {
+/** Parses the same YAML subset outside frontmatter, for `.reis-mobile/config.yaml`. */
+export function parseYamlSubset(text) {
   const data = {};
   const lines = text.split(/\r?\n/);
   let listKey = null;
+  let plainKey = null;
 
   for (let index = 0; index < lines.length; index++) {
     const line = lines[index];
@@ -29,11 +32,17 @@ function parseYamlSubset(text) {
       continue;
     }
 
+    if (plainKey && /^\s+\S/.test(line)) {
+      data[plainKey] = `${data[plainKey]} ${line.trim()}`;
+      continue;
+    }
+
     const pair = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
     if (!pair) continue;
 
     const [, key, value] = pair;
     listKey = null;
+    plainKey = null;
     const block = BLOCK_SCALAR.exec(value);
 
     if (block) {
@@ -47,6 +56,8 @@ function parseYamlSubset(text) {
       listKey = key;
     } else {
       data[key] = parseValue(value);
+      // Only an unquoted scalar can continue on the next lines.
+      if (typeof data[key] === 'string' && !/^["'[]/.test(value)) plainKey = key;
     }
   }
   return data;

package/core/registry/registry.mjs

@@ -3,11 +3,22 @@ import { basename, join } from 'node:path';
 
 import { DETECTABLE_STACKS } from '../detection/stack-detector.mjs';
 import { PLUGIN_ROOT } from '../paths.mjs';
-import { INTENT_IDS } from '../router/intents.mjs';
+import { AREA_IDS, INTENT_IDS } from '../router/intents.mjs';
 import { parseFrontmatter } from './frontmatter.mjs';
 
 export const ANY_STACK = '*';
 
+/**
+ * Every skill starts with `mobile-`. A topic skill covers every stack (`stacks: ["*"]`) with a
+ * reference per platform; a platform skill is named after the one stack it covers.
+ */
+export const PLATFORM_SKILLS = {
+  'mobile-flutter': 'flutter',
+  'mobile-android': 'android',
+  'mobile-ios': 'ios',
+  'mobile-rn': 'react-native',
+};
+
 /**
  * Loads stacks (`stacks/<id>/stack.json`), agents (`agents/<name>.md`) and skills
  * (`skills/<name>/SKILL.md`). Routing metadata lives in the same frontmatter Claude Code
@@ -68,6 +79,8 @@ function toComponent(kind, path, fileName, source) {
     description: data.description,
     intents: asList(data.intents),
     stacks: asList(data.stacks),
+    // Optional: the build areas (gradle, xcode, cocoapods...) a skill is specific to.
+    areas: asList(data.areas),
     // `routing: manual` marks helpers that Claude invokes by description only.
     routed: data.routing !== 'manual',
     // Third-party components declare where they came from (see THIRD_PARTY_NOTICES.md).
@@ -107,9 +120,23 @@ export function validateRegistry({ stacks, agents, skills }) {
 
     if (component.source && !component.license) errors.push(`${label}: "source" requires "license"`);
 
+    if (component.kind === 'skill' && component.name) {
+      const platform = PLATFORM_SKILLS[component.name];
+      if (!component.name.startsWith('mobile-')) {
+        errors.push(`${label}: skill name must start with "mobile-"`);
+      } else if (platform && !(component.stacks.length === 1 && component.stacks[0] === platform)) {
+        errors.push(`${label}: platform skill ${component.name} must declare stacks: [${platform}]`);
+      } else if (!platform && !(component.stacks.length === 1 && component.stacks[0] === ANY_STACK)) {
+        errors.push(`${label}: topic skill must declare stacks: ["*"], or be one of ${Object.keys(PLATFORM_SKILLS).join(', ')}`);
+      }
+    }
+
     for (const intent of component.intents) {
       if (!INTENT_IDS.includes(intent)) errors.push(`${label}: unknown intent "${intent}"`);
     }
+    for (const area of component.areas) {
+      if (!AREA_IDS.includes(area)) errors.push(`${label}: unknown area "${area}"`);
+    }
     for (const stack of component.stacks) {
       if (stack !== ANY_STACK && !stackIds.has(stack)) errors.push(`${label}: unknown stack "${stack}"`);
     }

package/core/router/intents.mjs

@@ -80,6 +80,8 @@ export const AREAS = [
   ['pub', ['pub get', 'pubspec', 'version solving']],
 ];
 
+export const AREA_IDS = AREAS.map(([id]) => id);
+
 // Areas that only exist on one native platform, used to focus cross-platform projects.
 export const AREA_PLATFORM = {
   gradle: 'android',

package/core/router/router.mjs

@@ -38,7 +38,7 @@ export async function route({ prompt = '', intent: explicitIntent, projectDir =
   const agent = intent ? selectAgent(components.agents, intent, stack) : null;
   if (intent && !agent) warnings.push(`No agent handles intent "${intent}" yet.`);
 
-  const skills = intent ? selectSkills(components.skills, intent, [stack, ...platformFocus]) : [];
+  const skills = intent ? selectSkills(components.skills, intent, [stack, ...platformFocus], parsed.area) : [];
 
   return {
     intent,
@@ -64,13 +64,18 @@ export function selectAgent(agents, intent, stack) {
   );
 }
 
-/** Skills for the primary stack first, then focused platforms, then stack-agnostic ones. */
-export function selectSkills(skills, intent, stacks) {
+/**
+ * Skills for the primary stack first, then focused platforms, then stack-agnostic ones.
+ * Among skills of the same stack, one declaring the detected area ("gradle", "cocoapods"...)
+ * comes first, so the model reads the most specific checklist before the general one.
+ */
+export function selectSkills(skills, intent, stacks, area = null) {
+  const areaScore = (skill) => (area && skill.areas?.includes(area) ? 1 : 0);
   return skills
     .filter((skill) => skill.routed && skill.intents.includes(intent))
-    .map((skill) => ({ skill, score: stackScore(skill.stacks, stacks) }))
+    .map((skill) => ({ skill, score: stackScore(skill.stacks, stacks), area: areaScore(skill) }))
     .filter(({ score }) => score > 0)
-    .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
+    .sort((a, b) => b.score - a.score || b.area - a.area || a.skill.name.localeCompare(b.skill.name))
     .map(({ skill }) => skill);
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "reis-mobile",
-  "version": "0.3.6",
-  "description": "AI agents, skills and workflows for Flutter, Android, iOS and React Native development.",
+  "version": "0.5.0",
+  "description": "AI agents and skills for mobile development — Flutter, Android, iOS and React Native — as a plugin for Claude Code and Codex: code review, debugging, tests, architecture, security and Firebase.",
   "type": "module",
   "license": "MIT",
   "author": "Warleson Reis",
@@ -31,5 +31,26 @@
     "validate": "node bin/reis-mobile.mjs validate",
     "check": "npm run validate && npm test"
   },
-  "keywords": ["mobile", "flutter", "android", "ios", "react-native", "claude-code", "plugin", "agents"]
+  "keywords": [
+    "flutter",
+    "android",
+    "ios",
+    "react-native",
+    "expo",
+    "swift",
+    "swiftui",
+    "kotlin",
+    "jetpack-compose",
+    "dart",
+    "firebase",
+    "mobile",
+    "mobile-development",
+    "claude-code",
+    "claude-code-plugin",
+    "codex",
+    "agent-skills",
+    "skills",
+    "ai-agents",
+    "code-review"
+  ]
 }

package/skills/mobile-android/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: mobile-android
+description: Builds native Android apps with the Android team's guides — Jetpack Compose UI, adaptive layouts, edge-to-edge, Compose styles, migrating XML views to Compose, Navigation 3 and predictive back; Android Gradle Plugin 9 upgrades, R8 keep rule analysis, profiling with Android Studio and Perfetto, and the Android CLI; Google Play policy compliance, Play Billing upgrades and the Engage SDK; Credential Manager restore and verified email; CameraX and Media3 Cast; App Functions and the ML Kit GenAI Prompt API; Wear OS, Android TV and display glasses. Use when writing, upgrading or auditing native Android (Kotlin) code for any of these topics, even if the user does not name the library.
+intents: [performance, release, migration, build, dependency]
+stacks: [android]
+---
+
+# Mobile Android
+
+Guides for building native Android apps, most of them from the Android team (`android/skills`). Cross-platform topics live in their own skills and have Android references there: architecture in `mobile-architecture`, tests in `mobile-test`, debugging (Gradle, crashes, ANRs) in `mobile-debug`, code review in `mobile-code-review`, security in `mobile-security` and Firebase in `mobile-firebase`.
+
+## Pick the topic
+
+| Topic | Read |
+|---|---|
+| UI and navigation | [references/ui.md](references/ui.md) |
+| Build, performance and tooling | [references/build-and-performance.md](references/build-and-performance.md) |
+| Google Play | [references/play.md](references/play.md) |
+| Identity | [references/identity.md](references/identity.md) |
+| Camera and media | [references/media.md](references/media.md) |
+| On-device AI | [references/on-device-ai.md](references/on-device-ai.md) |
+| Other form factors | [references/devices.md](references/devices.md) |
+
+Each topic file lists its guides; open only the ones the task needs.
+
+## Before writing code
+
+- Check the AGP, Kotlin, Compose BOM and `compileSdk`/`targetSdk` versions in the build files and version catalog; several guides depend on minimum versions.
+- Several guides prescribe running specific tools or scripts and following steps strictly; run what writes files only with the user's agreement.

package/skills/mobile-android/references/build-and-performance/agp-9-upgrade/GUIDE.md

@@ -0,0 +1,87 @@
+> Adapted from the `agp-9-upgrade` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
+
+## Migration guide
+
+See the [AGP 9 migration guide](references/android/build/releases/agp-9-0-0-release-notes.md) for the major changes, many
+breaking, in AGP 9 compared to AGP 8.
+
+## Requirements
+
+If the user requests to update or migrate to AGP 9, first check the AGP version
+used in the project. If it is lower than 9, stop and ask the user to run the AGP
+Upgrade Assistant in Android Studio to update to the latest stable version of
+AGP, and confirm when done. The user may also request that this requirement be
+skipped; if this is the case, you should update the version of AGP to the latest
+stable version as part of the AGP 9 migration. See the
+[AGP 9 migration guide](references/android/build/releases/agp-9-0-0-release-notes.md) for how to do this.
+
+Each version of AGP has its own set of compatibilities with other tools, such as
+Gradle, JDK, and Kotlin. The release notes for each of these versions will
+include a **Compatibility** table indicating the minimum versions for these
+tools.
+
+Do not use this skill for KMP projects, as they are unsupported.
+
+## Steps
+
+If AGP is already at 9 or higher, then do the following:
+
+### Step 1: Update dependencies
+
+If KSP (`com.google.devtools.ksp`) is used in the project, ensure it is on
+version 2.3.6 or higher.
+
+If Hilt is used in the project, ensure it is on version 2.59.2 or higher.
+
+### Step 2: Migrate to built-in Kotlin
+
+See [the guide](references/android/build/migrate-to-built-in-kotlin.md) for detailed information.
+
+### Step 3. Migrate to the new AGP DSL
+
+See [the guide](references/android/build/releases/agp-9-0-0-release-notes.md) for detailed information.
+
+See also [gradle-recipes](references/recipes.md) for examples on how to migrate old code to code
+that is compatible with AGP 9 and the new DSL.
+
+### Step 4. Migrate kapt to KSP or legacy-kapt
+
+If KSP (`com.google.devtools.ksp`) or kapt (`org.jetbrains.kotlin.kapt`) are
+used in the project, see [KSP, kapt, and legacy-kapt](references/ksp-kapt.md) for detailed migration
+steps.
+
+### Step 5. BuildConfig
+
+If any Android module contains custom BuildConfig fields, see [BuildConfig](references/buildconfig.md)
+for detailed information.
+
+### Step 6. Update gradle.properties
+
+After the migration, check gradle.properties. Remove the following flags:
+
+1. android.builtInKotlin
+2. android.newDsl
+3. android.uniquePackageNames
+4. android.enableAppCompileTimeRClass
+
+Additionally, delete all temporary files you've created.
+
+## Guidelines
+
+- Never write or run python scripts.
+- Only search the Gradle dependency cache when inspecting external dependencies, and only as a last resort.
+- Never add `android.disallowKotlinSourceSets=false` to `gradle.properties`.
+- When verifying changes, don't run the `clean` task. This is a waste of time.
+
+## Verification
+
+After migration, verify the following:
+
+1. Gradle IDE sync succeeds.
+2. `./gradlew help` succeeds.
+3. `./gradlew build --dry-run` succeeds.
+
+## Troubleshooting
+
+Paparazzi v2.0.0-alpha04 and lower versions have issues with AGP 9. See
+[references/paparazzi-gradle-9.md](references/paparazzi-gradle-9.md) for details.