Add android app dev related scaffolding

AGENTS.md

@@ -34,6 +34,9 @@
 - `stacks/typescript`: framework-neutral Bun/TypeScript conventions.
 - `stacks/python`: optional Python API/shared-package workspace.
 - `stacks/ruby`: optional Ruby/Rails/Rack workspace conventions.
+- `stacks/android`: optional native Android (Kotlin/Compose) release and
+  publishing convention pack — no app scaffold, since app structure is too
+  product-specific to template.
 - `.context`: gitignored workspace-local scratch for Conductor and agents.
 
 ## Development Workflow
@@ -72,6 +75,10 @@
   `cooldown:` source option requires Bundler `4.0.13` or newer. If Bundler is
   older, ask before upgrading it; do not add cooldown syntax that the target
   repo's Bundler cannot parse.
+- When selecting the Android stack, do not assume F-Droid distribution or
+  hand-edit `versionCode`/`versionName` — see `stacks/android/README.md` for
+  the versioning model and the GPL-3/free-software-dependency constraint,
+  which only applies when the target app actually targets F-Droid.
 - The TypeScript stack includes Drizzle examples for database access. Keep
   Drizzle when it fits; replace it when the target repo already uses another
   data-access layer.

MANIFEST.md

@@ -77,6 +77,7 @@ Disposition tags:
 | `stacks/typescript/pnpm/` | `select-per-stack` | pnpm root files and CI fragment for pnpm workspaces. |
 | `stacks/python/` | `select-per-stack` | Optional uv Python API/shared-package workspace with Ruff, MyPy, Pytest, Pydantic, and Alembic examples. |
 | `stacks/ruby/` | `select-per-stack` | Optional Ruby/Rails/Rack conventions with Bundler cooldown guidance. |
+| `stacks/android/` | `select-per-stack` | Native Android (Kotlin/Compose) convention pack: release-please versioning, GitHub Actions release pipeline, Google Play and F-Droid (self-hosted + f-droid.org) publishing, and recurring architecture decisions. |
 
 ## Extras Inventory
 

README.md

@@ -20,6 +20,9 @@ Point an agent at this repo when starting or normalizing a project. The agent sh
   shown first.
 - Optional `uv` Python workspace conventions.
 - Optional Ruby/Rails/Rack conventions.
+- Optional native Android (Kotlin/Compose) release and publishing
+  conventions: release-please versioning, a GitHub Actions release pipeline,
+  and Google Play/F-Droid publishing.
 - Dependency cooldowns for Bun, pnpm, uv, and Bundler.
 - Host-run development services.
 - Docker Compose examples for local infrastructure such as databases and
@@ -170,6 +173,10 @@ is a template source, not an installable preset or final generated app.
 - `stacks/python/`: optional Python API/shared-package workspace.
 - `stacks/ruby/`: optional Ruby/Rails/Rack conventions with Bundler cooldown
   guidance.
+- `stacks/android/`: optional native Android (Kotlin/Compose) convention
+  pack — release-please versioning, a GitHub Actions release pipeline, and
+  Google Play/F-Droid publishing. No app scaffold; app structure is too
+  product-specific to template.
 - `stacks/typescript/pnpm/`: pnpm root files and CI fragment for larger TypeScript workspaces.
 - `extras/dev-scripts/`: JS-first script variants and JS implementations of helper scripts.
 - `extras/dockerfiles/`: opt-in Dockerfile examples for deployment parity.
@@ -196,8 +203,8 @@ selection and pruning before feature work.
 - Start with root hygiene files, then select only the stacks and extras that
   match the target repo.
 - Treat `stacks/` as peer language/runtime convention packs. TypeScript and
-  Python are examples, not universal defaults. Ruby is available as an
-  opt-in convention pack when the target repo actually uses Ruby.
+  Python are examples, not universal defaults. Ruby and Android are available
+  as opt-in convention packs when the target repo actually uses them.
 - Treat `extras/` as opt-in workflows or deployment helpers that may require
   repo settings, real owners, or team process.
 - Keep `.context/` gitignored. Promote durable learnings into tracked docs

docs/deployment.md

@@ -25,6 +25,22 @@ When applying this devkit to a project, record the deployment decision here:
 | Coolify | Self-hosted platform-style deploys. | Adds a platform to operate and upgrade. |
 | Kubernetes | Larger teams with existing cluster operations. | Too much machinery for most new projects. |
 
+## Mobile Store Publishing
+
+Native mobile apps aren't a deployment-platform decision at all — there's no
+server to host. If the target project selects `stacks/android`, use its
+release pipeline instead of anything in this file: `version.txt` +
+release-please decide the version, a release-PR merge is what ships it, and
+CI publishes signed builds to GitHub Releases, Google Play (internal track),
+and F-Droid (a self-hosted repo plus an optional f-droid.org submission). See
+`stacks/android/README.md` for the full model, including why the two jobs
+live in one workflow run and how signing keys are handled.
+
+The target repo's own `docs/deployment.md` should be rewritten to describe
+that concrete pipeline rather than keeping this file's generic
+platform-decision-record shape — see `stacks/android/README.md` → "Docs To
+Write In The Target Repo".
+
 ## Workflow Guidance
 
 Keep deployment workflows platform-specific and explicit. A project should add deploy CI only after the platform is chosen and secrets are configured.

docs/supply-chain.md

@@ -108,6 +108,22 @@ Use `cooldown: 0`, `bundle install --cooldown 0`, or `BUNDLE_COOLDOWN=0` only
 for intentional exceptions such as emergency security fixes. Document the
 exception in the PR or release note.
 
+## Gradle (Android)
+
+Use this when a project selects the Android stack (`stacks/android`).
+
+Gradle has no package-manager-level cooldown flag comparable to Bun/uv/pnpm/
+Bundler. Renovate is the whole mechanism: it natively understands Gradle
+version catalogs and opens PRs against `gradle/libs.versions.toml` on the
+repo's normal `minimumReleaseAge`, no extra Renovate config required. Don't
+hand-edit dependency versions in that file opportunistically outside of a
+Renovate PR unless fixing something broken.
+
+Verify Gradle wrapper integrity via `distributionSha256Sum` in
+`gradle/wrapper/gradle-wrapper.properties`, and update both together when
+bumping the wrapper version. CI should build against the committed wrapper
+only — never a floating Gradle version.
+
 ## CI
 
 Use frozen or locked installs:

docs/tooling.md

@@ -84,6 +84,42 @@ adapt to `bin/dev`, Rails, Rack, RSpec, or Minitest-style test directories.
 When adding Bundler cooldowns, require Bundler `4.0.13` or newer and pin that
 Bundler version in `Gemfile.lock` before handing off the target repo.
 
+## Android Stack
+
+Use `stacks/android` for native Android (Kotlin + Jetpack Compose) projects.
+Unlike the other stacks, its reusable part is the release/publishing pipeline
+and a set of recurring architecture decisions, not a local-dev script set —
+see `stacks/android/README.md` for the full rationale.
+
+Required checks for `stacks/android`:
+
+```bash
+./gradlew ktlintCheck
+./gradlew testDebugUnitTest
+./gradlew lintDebug
+./gradlew assembleDebug
+```
+
+Track Gradle/Kotlin/Compose/library versions in `gradle/libs.versions.toml`
+in the target repo, not in this devkit — Renovate natively understands Gradle
+version catalogs and opens PRs against it on the repo's normal cooldown,
+which is the expected update path. Don't hand-edit versions opportunistically
+outside of that unless fixing something broken.
+
+**AGP 9+ has built-in Kotlin support.** Do not apply
+`org.jetbrains.kotlin.android` (`kotlin-android`) alongside it — AGP 9.0+
+compiles Kotlin itself, and applying that plugin on top is a hard build
+error, not a warning. See `stacks/android/README.md` for the rest of the
+recurring Android decisions (Compose over Views, no DI framework by default,
+Room vs. a flatter store, SDK level defaults, and the reverse-DNS
+application-ID gotcha).
+
+The GPL-3/free-software-dependency constraint (AndroidX and
+Kotlin-stdlib-class libraries only, no Google Play Services, no Firebase) is
+specific to apps that target F-Droid distribution. Confirm that goal with the
+user before applying it or the F-Droid publishing pipeline — not every
+Android app in this devkit's scope needs either.
+
 ## Dependency Safety
 
 Use dependency cooldowns and frozen installs:

llms.txt

@@ -27,6 +27,10 @@
 - Use deterministic worktree ports from `scripts/worktree-ports.sh`.
 - Keep `.context/` gitignored and workspace-local; durable knowledge belongs in tracked docs.
 - Put language/runtime conventions in `stacks/` and opt-in add-ons in `extras/`.
+- `stacks/android` covers native Android release/versioning/publishing
+  conventions (release-please, GitHub Actions, Play, F-Droid) — no app
+  scaffold. Never hand-edit `versionCode`/`versionName`; derive them with
+  `scripts/sync-version.sh` from `version.txt`.
 - Before applying the devkit, use `MANIFEST.md` to produce a selection report
   covering every top-level path in the devkit and target repo.
 

skills/508-devkit/SKILL.md

@@ -15,8 +15,8 @@ Canonical repo: https://github.com/508-dev/508-devkit
 - Root files provide broadly useful hygiene: agent instructions, shell
   entrypoints, worktree-safe ports, Docker Compose examples, GitHub templates,
   dependency cooldowns, and docs.
-- `stacks/` contains language/runtime convention packs. TypeScript, Python, and
-  Ruby are examples, not universal defaults.
+- `stacks/` contains language/runtime convention packs. TypeScript, Python,
+  Ruby, and Android are examples, not universal defaults.
 - `extras/` contains opt-in add-ons such as Dockerfiles, dev containers,
   object storage, CODEOWNERS, Gitleaks, Dependency Review, and TODO-to-issue.
 - `.context/` is workspace-local agent scratch and must not be committed.
@@ -40,6 +40,8 @@ example app, or design-history document.
    - `pyproject.toml`, `uv.lock` when Python is present.
    - `Gemfile`, `Gemfile.lock`, `.ruby-version`, `gems.rb`, and `gems.locked`
      when Ruby is present.
+   - `build.gradle.kts`, `settings.gradle.kts`, `gradle/libs.versions.toml`
+     when native Android is present.
    - `package.json`, `bun.lock`, `pnpm-lock.yaml`, `bunfig.toml`, `pnpm-workspace.yaml`.
    - Compose files.
    - `.github/workflows`.
@@ -64,6 +66,13 @@ example app, or design-history document.
    - Use the Ruby stack only when the target repo is Ruby or the user asks for
      Ruby conventions. Treat Rails and Rack paths as adaptive examples, not
      requirements.
+   - Use the Android stack only when the target repo is a native Android app.
+     It has no app scaffold — only release/versioning/publishing conventions
+     (release-please, GitHub Actions release pipeline, Google Play, F-Droid)
+     and a list of recurring architecture decisions to open a `DECISIONS.md`
+     entry against. Confirm F-Droid distribution is an actual goal before
+     applying its GPL-3/free-software-dependency constraint or F-Droid
+     publishing pipeline.
    - Use Drizzle examples only when TypeScript-side database access is wanted
      and Drizzle fits the repo. Keep an existing data-access layer when one is
      already established.
@@ -162,3 +171,15 @@ Before writing Bundler dependency cooldowns, run `bundle --version`.
 newer. If the target machine has an older Bundler, ask before upgrading it. Once
 cooldown is added, pin the compatible Bundler version in `Gemfile.lock` with
 `bundle lock --bundler=4.0.13` or newer.
+
+## Android Release Versioning
+
+Never hand-edit `versionCode`, `versionName`, or `CHANGELOG.md` in a repo
+using `stacks/android`. `version.txt` is the source of truth; change that and
+run `scripts/sync-version.sh`, which derives `versionCode` as
+`major * 1000000 + minor * 1000 + patch` and keeps both values as plain
+literals in `app/build.gradle.kts` — F-Droid's update bot regex-parses them
+textually, so turning them into an expression silently ends automatic
+F-Droid releases. See `stacks/android/README.md` for the full release model
+(release-please, the two-jobs-in-one-workflow-run gotcha, and Play/F-Droid
+publishing).