@1aboveio/skills 1.0.13 → 1.0.15

package/skills/app-dev/android-development/references/framework-choice.md

@@ -0,0 +1,88 @@
+# Choose Kotlin/Compose or React Native
+
+Choose the smallest design that preserves the required behavior and reduces demonstrated
+coordination cost. Recommend a concrete default below; do not answer a framework decision
+with only "it depends." Apply the product's platform requirements and existing ADRs first.
+If one missing requirement would reverse the choice, name that requirement and ask for it.
+
+## Choose by situation
+
+| Situation | Recommendation | What must hold |
+| --- | --- | --- |
+| Existing React Native app; delay is repeated builds, cold setup or oversized verification | Keep React Native and repair the development loop. Do not propose migration for this evidence. | JS edits use the compatible running app; native edits use the verified incremental path; required acceptance stays intact. |
+| New flow with required Android/iOS UI reuse, mostly forms, lists and API interaction | Prefer React Native. Use platform-specific code only for demonstrated platform needs. | Verify the required native SDKs and platform behavior can be integrated without unacceptable ownership/synchronization costs. |
+| New Android-only flow dominated by hardware/SDK interaction, IME/Back/focus, windows or Activity lifecycle | Prefer Kotlin with Jetpack Compose as the starting design. Keep the related UI state and lifecycle under one coherent native owner. | Android-only scope is confirmed; backend/security contracts and required validation remain unchanged. Kotlin is not a promise of faster builds. |
+| Existing React Native flow repeatedly fails at demonstrated RN/native event or state coordination | First remove duplicated authority in the existing design. If that cannot meet the requirement, recommend an explicitly authorized Kotlin-owned coherent screen/flow as the next candidate, not many tiny bridged controls. | Define the boundary and its API, navigation and lifecycle responsibilities. Compare retained integration cost with the coordination being removed; preserve iOS obligations. |
+| Product-wide migration proposed, or platform/reuse/maintenance trade-offs remain unresolved | Keep the current stack for ordinary delivery. Present the candidate decision and obtain authorization for a bounded comparison or architecture change. | No migration, standalone host, benchmark campaign or new framework is implied by an ordinary bug fix. |
+
+Use the native-heavy recommendation for new design decisions, not as permission to rewrite
+working React Native code. A single native SDK is not by itself a reason to migrate a whole
+app. Conversely, shared UI is not a reason to force a platform-specific workflow through
+multiple owners when the required behavior cannot be supported reliably.
+
+## Compare the actual development paths
+
+| Dimension | React Native with native modules | Kotlin with Jetpack Compose |
+| --- | --- | --- |
+| UI styling and state iteration | Fast Refresh/reload can update supported JS/TS edits in an owned running debug app without a native build. | Compose Preview/Live Edit can help when the actual tooling supports them; structural changes still require compilation/deployment. |
+| Business logic | Focused JS/TS tests and runtime debugging; native contracts still need composition proof. | Focused Kotlin/JVM tests and runtime debugging; platform/backend contracts still need composition proof. |
+| Android APIs, hardware and SDKs | Native modules or components add a contract between JS and Android when needed. | Direct Android API/SDK integration can remove that cross-runtime adapter. |
+| IME, Back, focus and window lifecycle | Define ownership across the React tree, native component and Android host; asynchronous events must not create competing authority. | A coherent native screen can reduce inter-framework coordination, but still needs correct state, event and lifecycle handling. |
+| Build feedback | JS-only feedback can avoid Gradle; changed native inputs require native rebuilding. | Native changes use the supported incremental build/run path; Kotlin is not automatically a cheaper cold build. |
+| Tests | May combine JS, JVM, instrumentation and device journeys. | May combine JVM, instrumentation and device journeys; one UI toolkit does not eliminate integration or acceptance layers. |
+| Android/iOS reuse | Can share UI and logic, with explicit platform-specific behavior. | An Android Compose UI does not supply an iOS UI. Account for separate iOS work or an independently approved sharing strategy. |
+
+For an agent, compare tools it can actually operate. Do not count Android Studio Preview or
+Live Edit as available feedback in a headless CLI workflow without verifying access. Live
+Edit has edit/runtime constraints; preview or live updates do not prove native interaction,
+packaged startup or release behavior. Use the pinned toolchain, not assumed IDE capabilities.
+
+## Decide where ownership belongs
+
+For a native-heavy editor or sheet, assign one authoritative owner for draft state,
+Apply/Cancel, IME/Back handling and focus restoration. Define who accepts the final result
+and rejects stale events. Prefer a coherent screen/flow boundary over splitting each
+gesture and transition across runtimes. Keep business authorization and backend authority
+where the product contract requires them; moving UI ownership does not transfer those powers.
+
+Do not delete process-death recovery, persistence, identity, authorization, stale-callback
+guards or tests just because a bridge disappears. Identify which adapters become unnecessary
+and which correctness contracts remain. More Kotlin inside a React Native host may retain
+the boundary; it is not evidence for a pure-native architecture's cost.
+
+## Make and report the decision
+
+1. State the recommendation first: keep React Native, use React Native for the new flow,
+   prefer Kotlin/Compose for the new Android-only flow, or evaluate a specific native-owned
+   boundary. Name the platform and behavior facts that support it.
+2. Fix avoidable feedback-loop costs before comparing engineering effort: no repeated cold
+   setup, unnecessary test packaging or all-ABI build for every local edit. Keep the
+   [validation ladder](../SKILL.md#validation-ladder) and required CI in both paths.
+3. If a comparison is authorized, use the same representative behavior, backend/security
+   contracts and acceptance criteria. Compare total implementation/debug/verification effort,
+   failed iterations and their causes, plus build/startup cost using existing records.
+   Adapter lines are supporting evidence, not the decision metric. Do not invent timings,
+   a universal percentage threshold, or a new metrics service.
+4. A standalone native host can test whether an interaction becomes simpler, but excludes
+   production integration, navigation, deployment and iOS costs. Report that scope separately;
+   do not compare its narrow success with full production acceptance as equivalent work.
+5. Recommend adoption only for the scope supported by the evidence. Record platform/reuse
+   trade-offs, retained contracts, transition/rollback costs and unresolved proof in the
+   project's existing decision record. Ask for approval before changing an established stack
+   or launching a new experiment. Continue ordinary fixes within their authorized scope.
+
+## Avoids
+
+- Do not choose a framework from one slow build, a PR count or generic "excellent" ratings.
+- Do not promise that Kotlin removes Android lifecycle or backend correctness obligations.
+- Do not replace an optimized React Native baseline with an artificially cheap native demo.
+- Do not turn this guide into a Kotlin-only preference, mandatory experiment or migration gate.
+- Do not assume Android-only deployment or that cross-platform reuse has no product value.
+
+## Public tooling references
+
+Check behavior against the project's versions before selecting a feedback mechanism:
+
+- [React Native 0.81 build scope and ABI selection](https://reactnative.dev/docs/0.81/build-speed)
+- [Expo local development and Metro reuse](https://docs.expo.dev/guides/local-app-development/)
+- [Compose iterative development and Live Edit limitations](https://developer.android.com/develop/ui/compose/tooling/iterative-development)

package/skills/app-dev/{android-foundation → android-development}/references/gotchas.md

@@ -1,4 +1,36 @@
-# Android foundation gotchas
+# Android development gotchas
+
+## Triage
+
+Name the earliest stage that failed. In CI, that is the first failed step. If the same
+journey passed on another run of the same commit, suspect the run or the journey before
+the product.
+
+| Stage | Typical signal |
+| --- | --- |
+| Prerequisites / install | missing SDK directory, wrong JDK, lockfile drift |
+| Harness unit tests (CI, before the APK) | a harness test fails on host state its fixture should fake (`requires 2 GiB reserve`) |
+| Export / APK | Metro bundling error, Gradle compile or dependency-resolution error |
+| Gradle network | Maven download or TLS-handshake errors on a cold build: fix routing, not code |
+| Emulator boot / ADB | `sys.boot_completed` never reaches 1, device offline, exit 124 |
+| Device to Metro | red box, "unable to load script", missing `adb reverse` mapping |
+| Bridge passes, debug app fails to load | possible app/probe endpoint mismatch; inspect the actual request before choosing a cause ([React Native example](diagnosis.md#example-react-native-debug-app-uses-another-metro)) |
+| Device to Metro, mid-journey | a screen's first Metro asset fails (`Unable to download asset from url: http://127.0.0.1:8081/assets/…`) while API calls still succeed |
+| Backend / Login | backend log errors, verification code not found in the database |
+| Backend tool, CI only | a Backend-backed step gets a 5xx in CI only; the log names a missing program (`Browser was not found at the configured executablePath`) |
+| adb transport, mid-journey | `connection terminated: read failed` in the adb trace after boot, then lost `adb reverse`: usually guest RAM |
+| UiAutomator server | `RemoteDisconnected` while the adb transport stays up: the on-device server was relaunched |
+| Journey harness | a wait right after a navigation times out while the destination is on screen |
+| Journey harness, short screen | a wait for a label times out only on a short or landscape screen, which shows the content above it |
+| Product assertion | a screen or state mismatch with a screenshot |
+
+Then match the signal against [gotchas.md](gotchas.md). If nothing
+matches, [confirm the suspected cause](gotchas.md#confirm-a-suspected-cause)
+before changing code.
+
+Preserve the failure evidence. Do not blindly replay steps that send codes, verify sessions
+or charge payments just to get a passing screenshot. One passing run does not prove the
+build is reliable.
 
 Known traps, each as signal, cause and fix. Match the signal before you dig. If none
 matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changing code.
@@ -58,10 +90,12 @@ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changi
   recovers, Metro becomes unreachable, and a debug build loads assets from Metro. A
   backend reached at `10.0.2.2` does not use adb, so it keeps working. The usual trigger is
   an [adb transport drop](#the-adb-transport-drops-mid-journey); fix that first.
-- **Fix:** re-prove the bridge before every step whose screen is the first to load a Metro
-  asset: re-apply the reverse and check, from inside the device, that Metro answers. Doing
-  it only at app launch is not enough. Release builds embed their assets, so this is a
-  harness failure, not a product failure.
+- **Fix:** after a transport reconnect or observed mapping loss, restore the owned reverse
+  and verify device-to-Metro loading before continuing the affected check. Preserve a
+  harness's required checkpoints, but do not reset mappings or probe every screen by
+  default in an unchanged warm session. Determine the selected variant's real asset
+  mechanism before classifying the failure; an absent mapping alone does not prove
+  that the harness rather than the app caused the disconnect.
 
 ### The adb transport drops mid-journey
 
@@ -191,7 +225,10 @@ matches, [confirm the suspected cause](#confirm-a-suspected-cause) before changi
 
 - **Cause:** the slot's tool cache is empty, so the JDK or Python downloads from the
   internet.
-- **Fix:** seed the runner's `_tool/` directory from a sibling slot with the same image.
+- **Fix:** report the cold tool cache and hand provisioning to the runner owner through
+  `github-actions` and the fleet policy. A compatible cache seed may be their remedy;
+  do not copy or mutate either slot's shared `_tool/` state during an ordinary Android
+  diagnosis without a separate provisioning assignment.
 
 ### A Backend call fails only in CI: the runner lacks a tool the app launches
 

package/skills/app-dev/android-development/references/init.md

@@ -0,0 +1,126 @@
+# Project initialization
+
+`android-development` persists one section of project Android guidance. This helper is the
+deterministic writer behind that setup; `SKILL.md` owns the interactive choice that decides
+whether anything is persisted.
+
+## Usage
+
+```sh
+node {baseDir}/scripts/init.mjs [--repo-root <dir>] [--write]
+```
+
+- Preview is the default: it prints the planned action per file and writes nothing.
+- `--write` applies the plan. `--repo-root` selects the project; without it the nearest Git root
+  from the current directory is used, falling back to the current directory when there is none.
+- `--help` prints the usage line.
+- An unknown argument, an unresolvable root, a malformed marker, an unsafe target or a file that
+  ends inside an unclosed fenced code block or HTML comment exits non-zero with a message and no
+  writes, in preview and with `--write` alike.
+
+## Files and ownership
+
+When Project or explicit init is selected, preview with the command above, then apply it
+with `--write` for the authorized missing additions. Existing conflicting policy needs a
+decision, not an overwrite. Verify the repo's actual commands and add only known bindings
+to a newly created Android section; report unresolved commands instead of guessing them.
+
+| File | Write |
+| --- | --- |
+| `CONTRIBUTING.md` | The `## Android development` section, wrapped in `<!-- conventions:android:start -->` / `<!-- conventions:android:end -->`, with `references/android-conventions.md` as its body. |
+| `AGENTS.md` | An `Android task entry` skill-loading block between `conventions:android-task-entry` markers, plus a pointer to the selected `CONTRIBUTING.md` when missing. Check these independently: a contributor-guide link alone is not a skill loader. |
+
+Each file is created only when it is absent. The helper never edits `CLAUDE.md`, never writes into
+a parent project, a home directory or global agent configuration, and never reaches outside the
+selected root.
+
+After applying authorized additions, verify that each existing supported agent entrypoint
+reaches both the skill task-entry instruction and the Android contributor-guide section,
+directly or through its instruction chain. A direct link to `CONTRIBUTING.md` does not
+establish that the entrypoint loads the skill rule in `AGENTS.md`. The helper configures
+`AGENTS.md`; it does not certify an independent `CLAUDE.md` loader. Preserve existing chains
+and do not edit that entrypoint under this init permission. If one does not reach the guide,
+report the files configured and the unresolved loading path as partial setup. Obtain separate
+authorization for any additional loader edit instead of silently claiming complete setup.
+
+The task-entry block requires reading and applying the installed `android-development`
+skill before Android-specific commands, during issue-unit preflight, in delegated Android
+workers, and again after compaction when its rules are lost. Keep commands and validation
+policy in `CONTRIBUTING.md`, not this loader. An existing direct read/load-before rule or
+managed block is preserved. A managed block is preserved only while it still holds an active
+loader: an empty block, or one whose only loader is commented out or written as a code example,
+is refused rather than counted as configured. A direct `do not load`-style rule that conflicts
+with the loader is refused too, wherever it sits in the file. Fenced code, indented code, HTML
+comments and inline code are documentation, so an example never counts as an active loader or as
+a conflict. An unrecognized `Android task entry` section requires manual reconciliation rather
+than a competing block. Inspect existing rules for conflicts before applying the helper; it
+cannot interpret every natural-language policy. This missing-loader addition is part of explicit
+init even in previously initialized repos, not an automatic update.
+
+## Resolve the repo command map
+
+The initializer, not the deterministic writer, inspects existing scripts and guidance.
+Prefer the repo's working development route over adding another wrapper. For a new Android
+section, persist verified bindings in that section using this compact convention:
+
+| Lane | Working directory and command | Inputs/artifacts and owner | Verification status |
+| --- | --- | --- | --- |
+| L0 | Existing Metro start/reuse, focused tests and typecheck | JS delivery endpoint and owned running app | Observed or unresolved |
+| L1 | Incremental native build/install | Actual device ABI, scoped override, Gradle graph, app vs test APKs | Observed or unresolved |
+| L2 | Candidate startup/install and selected journey | Candidate artifact, supported selectors and disposable state owner | Observed or unresolved |
+| L3 | Existing required CI and release checks | Required test artifacts, device/ABI matrix and acceptance owner | Existing binding requirement |
+
+Inspect wrapper/task expansion using [feature work](feature-work.md#verify-command-expansion)
+when the owned toolchain permits it; reading a script is not executing its graph. Record
+what was inspected versus run and leave missing evidence unresolved. Initialization does
+not require a cold build, emulator provisioning, CI dispatch or acceptance campaign.
+Record native/JS invalidation triggers and [development-session ownership](workspace.md).
+Do not invent a command, selector or flag to complete the table.
+
+On later init runs, preserve the existing section and manual bindings without refreshing
+them. An authorized correction to stale commands is a deliberate policy edit, not a side
+effect of initialization or a new skill version.
+
+## Preservation
+
+Existing guidance wins over the template:
+
+- An existing `## Android development` heading, marked or hand-written, is left byte-for-byte,
+  including any repository-specific commands a caller added.
+- Every other section, hand edit and file is preserved; initialization appends and never
+  rewrites, reorders or refreshes.
+- Repeating the same initialization leaves configured files unchanged. There is no `--force` and
+  no update path: a new skill release never replaces saved project policy.
+- A valid symlink inside the project stays a link and its target is updated once. A dangling
+  link, a link resolving outside the selected root, a directory, unreadable or non-UTF-8 content,
+  and two targets resolving to one file are refused. Every target is validated before the first
+  write, so a refusal leaves the project untouched.
+- Refuse a mutation of a multiply hard-linked file or of an alias to the protected
+  `CLAUDE.md` entrypoint. This includes a shared AGENTS/CLAUDE target: preserve it and
+  report the boundary rather than silently granting a new write permission.
+- Refuse an addition to a file that ends inside an unclosed fenced code block or HTML comment.
+  Appended guidance would land inside that construct, be inactive, and be appended again on
+  every run. The helper never closes it for you: preserve the manual text, repair the fence or
+  comment, and rerun. A file that needs no addition is reported unchanged, so an
+  already-configured project behind such a construct is not blocked.
+- An existing pointer is reused only when its link resolves to the selected `CONTRIBUTING.md`,
+  and a new pointer is written relative to the real location of `AGENTS.md`. A link to some other
+  file, such as a nested package guide, does not count as this project's loader.
+
+## What it does not do
+
+Initialization is not installation or delivery. It does not install dependencies, SDK components
+or devices, provision an emulator, generate CI, open issues, push or release. It does not
+discover commands automatically: the initializer follows the command map above and reports
+what it could not resolve. Adding verified repository-specific bindings to the new section is
+part of that explicit initialization; a
+conflicting existing rule is reported rather than overwritten.
+
+## Scope and overrides
+
+The section applies to the project root it was written in, for later sessions. A Session choice
+keeps the ladder in conversation only and writes no files or configuration, including after
+compaction; an ordinary Android task reads existing guidance and does not initialize or ask about
+setup by itself. `SKILL.md` owns that interactive choice and its lifetime.
+
+Initialization does not authorize a commit, push, pull request, enqueue or release.