geeknative 0.0.0-stage → 0.1.1

package/template/.geeknative/hooks/parity-guard.mjs

@@ -0,0 +1,49 @@
+// Claude Code Stop hook (managed by geeknative).
+// If the uncommitted changes touch some apps but not the others, remind the agent once,
+// since requests apply to all three apps unless they're platform-specific.
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+let input = ''
+for await (const chunk of process.stdin) input += chunk
+if (JSON.parse(input || '{}').stop_hook_active) process.exit(0)
+
+const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+/** Runs git in the project folder; paths come back relative to it. @param {string[]} args */
+const git = (...args) => spawnSync('git', args, { cwd: root, encoding: 'utf8' })
+
+const tracked = git('diff', '--name-only', '--relative', 'HEAD', '--', 'apps')
+const untracked = git('ls-files', '--others', '--exclude-standard', '--', 'apps')
+if (tracked.status !== 0 || untracked.status !== 0) process.exit(0) // not a git repo, or no commits yet
+
+// Generated code and agent docs don't count as implementing a change.
+const ignored = /(\/Generated\/|\/generated\/|\/generated_[^/]*\.xml$|Identity\.xcconfig$|identity\.properties$|AGENTS\.md$|CLAUDE\.md$)/
+const changed = [...tracked.stdout.split('\n'), ...untracked.stdout.split('\n')]
+  .filter((file) => file.startsWith('apps/') && !ignored.test(file))
+  .sort()
+
+const names = { ios: 'iOS', android: 'Android', web: 'web' }
+const touched = Object.keys(names).filter((p) => changed.some((file) => file.startsWith(`apps/${p}/`)))
+if (touched.length === 0 || touched.length === 3) process.exit(0)
+
+// Remind only once per set of changes.
+const fingerprint = createHash('sha1').update(changed.join('\n')).digest('hex')
+const stateFile = path.resolve(root, git('rev-parse', '--git-dir').stdout.trim(), 'geeknative-parity-guard')
+let last = ''
+try {
+  last = readFileSync(stateFile, 'utf8')
+} catch {}
+if (last === fingerprint) process.exit(0)
+writeFileSync(stateFile, fingerprint)
+
+const missing = Object.keys(names).filter((p) => !touched.includes(p))
+const list = (/** @type {string[]} */ platforms) =>
+  platforms.map((p) => names[/** @type {keyof typeof names} */ (p)]).join(' and ')
+console.error(
+  `Parity check: the uncommitted changes touch ${list(touched)} but not ${list(missing)}. ` +
+    'If this request applies to every app, implement it there too (AGENTS.md section 1). ' +
+    "If it's intentionally platform-specific, say so in your report and note it in the spec's Platform notes. Then finish.",
+)
+process.exit(2)

package/template/.geeknative/hooks/subagent-context.mjs

@@ -0,0 +1,24 @@
+// Claude Code SubagentStart hook (managed by geeknative).
+// Gives a platform subagent its platform's AGENTS.md as soon as it starts.
+// Usage: node subagent-context.mjs <ios|android|web>
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+const platform = process.argv[2]
+const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+
+let guide
+try {
+  guide = readFileSync(path.join(root, 'apps', platform, 'AGENTS.md'), 'utf8')
+} catch {
+  process.exit(0)
+}
+
+console.log(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStart',
+      additionalContext: `Conventions for this app, from apps/${platform}/AGENTS.md:\n\n${guide}`,
+    },
+  }),
+)

package/template/.geeknative/playbooks/bug.md

@@ -0,0 +1,7 @@
+# Playbook: bug
+
+1. **Locate.** Find which app has the bug, and whether that app breaks the spec or the spec never covered this case.
+2. **If the spec was silent or wrong,** fix the spec first (add the missing state or rule, with an acceptance criterion), then fix every app that doesn't match it. A bug in one app often exists in the others.
+3. **If the spec was right,** fix the app that breaks it, then check the other two apps for the same mistake.
+4. **Add a regression test** named after the acceptance criterion it protects, in each app you fixed.
+5. **Verify** with `make check` for every app you touched, and report which apps had the bug.

package/template/.geeknative/playbooks/design.md

@@ -0,0 +1,10 @@
+# Playbook: design change
+
+Use for look and feel: colors, type, spacing, corner radii, dark mode, density, or "make it feel more ...".
+
+1. **Direction first.** For a broad request ("warmer", "more premium"), update the Direction section of DESIGN.md in a sentence or two, so later changes stay consistent with it.
+2. **Tokens before code.** Change values in contracts/tokens.json. Keep light and dark values in step and text readable (WCAG AA: 4.5:1 for body text). Run `make gen`. Most visual changes need nothing else, because every app reads the tokens.
+3. **New tokens are roles.** Name new colors by purpose (`success`, `warning`), not by hue (`green`). Every app gets them on the next `make gen`.
+4. **Components.** If a change affects a pattern (for example, every card gets a border), update the Components table in DESIGN.md, then change that pattern in all three apps.
+5. **Stay native.** Change brand elements (color, type, spacing, imagery) everywhere, but keep platform conventions (navigation bars, system controls, gestures) native unless the user explicitly asks otherwise.
+6. **Verify** with `make check`. If you can, launch the apps (`make run-ios`, `make run-android`, `make run-web`) and look at the result.

package/template/.geeknative/playbooks/engineering.md

@@ -0,0 +1,9 @@
+# Playbook: engineering change
+
+Use for tooling, dependencies, build settings, refactoring and performance work that doesn't change what users see.
+
+1. **No spec changes** unless behavior changes. If it does, treat it as a feature or a bug instead.
+2. **Keep the apps mirrored.** If you change how state, navigation, data or dependencies work on one platform, make the matching change on the others, or record why not in spec/decisions.md.
+3. **Dependencies.** Prefer platform and first-party libraries, and ask before adding a large dependency. The iOS app has no third-party packages; adding one changes the Xcode project, so ask first.
+4. **Generated code.** Never edit generated files. Change the contract, or for a bug in the generator, report it upstream: codegen lives in the geeknative package.
+5. **Verify** with `make check` for every platform you touched.

package/template/.geeknative/playbooks/feature.md

@@ -0,0 +1,11 @@
+# Playbook: feature or behavior change
+
+1. **Spec.** For a new feature, copy .geeknative/templates/feature.md to `spec/features/<id>.md` (`id` in kebab-case). For a change, edit the existing spec. Write acceptance criteria that are testable and platform-neutral, numbered `AC-<id>-1`, `AC-<id>-2`, ...
+2. **States.** Cover loading, empty, error and success for every screen that loads or saves data. Missing states are the most common way apps drift apart.
+3. **Data.** Describe what's stored and in what format (keys, values, types), so every app stores it the same way. New data goes through a repository interface with a local implementation; there's no backend yet.
+4. **Navigation.** If the feature adds a screen, add it to spec/navigation.md.
+5. **Contracts.** Add copy to `contracts/strings/<locale>.json` (every locale), icons to contracts/icons.json and any new design tokens to contracts/tokens.json. Run `make gen`.
+6. **Implement** on iOS, Android and web, each following its `apps/<platform>/AGENTS.md` and using the same names everywhere: `<Name>Screen`, `<Name>ViewModel`, `<Name>Repository`.
+7. **Test** each acceptance criterion on each platform where it can be tested at the unit level, with the AC ID in the test name. Criteria that need UI tests can wait, but list them in your report.
+8. **Verify** with `make check`, and fix until it passes.
+9. **Record.** Set each platform's status in the spec's front matter (`done`, `in-progress`, `planned`, or `n/a` for a feature that's not on that platform). Run `make parity`. Add new features to PRODUCT.md's feature list.

package/template/.geeknative/playbooks/platform-specific.md

@@ -0,0 +1,8 @@
+# Playbook: platform-specific change
+
+Use when the user names a platform ("on Android, ...", "iOS only").
+
+1. **Check it's really platform-only.** Platform conventions (haptics, share sheets, widgets, keyboard shortcuts on web) belong on one platform. A product change that merely happens to be described for one platform probably belongs on all three. If unsure, ask once.
+2. **Record it** in the feature's "Platform notes" if users can see it, so nobody "fixes" the difference later. For a feature that exists on only some platforms, set the others to `n/a` in its front matter.
+3. **Implement and verify** on that platform only, with `make check-<platform>`.
+4. **Report** that the change is intentionally limited to that platform.

package/template/.geeknative/playbooks/product.md

@@ -0,0 +1,12 @@
+# Playbook: product
+
+Use when the user describes an app (often the first prompt in a new project), or changes what it is, who it's for, or its scope.
+
+1. **Understand.** Restate the product in one sentence. Ask only about things that would change the data model or the navigation structure (AGENTS.md section 6), and assume the rest.
+2. **PRODUCT.md.** Fill in the one-sentence description, the audience, the feature list, the glossary and what's out of scope. Glossary terms become the names used in code on every platform.
+3. **Design.** If the user described a look, write the direction in DESIGN.md and update contracts/tokens.json (colors in light and dark, type, spacing, radii). Run `make gen`.
+4. **Navigation.** Update spec/navigation.md with the screens and how users move between them (tabs, stacks, modals). Keep the starter Settings screen unless the user says otherwise.
+5. **Feature specs.** Write one spec per feature in spec/features/, starting from .geeknative/templates/feature.md, with every platform's status set to `planned`. Keep version one small: the core loop first.
+6. **Build in vertical slices.** Take the first feature through the loop in AGENTS.md section 4 on all three apps, verify it, record its status, then start the next. Never build every screen on one platform first.
+7. **Replace the starter content.** Once real features exist, update or remove Home's welcome card, and update spec/features/home.md to match.
+8. **Report** what you built on each platform, what's planned next, and the assumptions you made.

package/template/.geeknative/templates/feature.md

@@ -0,0 +1,49 @@
+---
+id: feature-id          # kebab-case; used in file names and acceptance criteria IDs
+title: Feature title
+status:                 # planned | in-progress | done | n/a (not on this platform)
+  ios: planned
+  android: planned
+  web: planned
+---
+
+# Feature title
+
+## Summary
+
+One or two sentences: what the user can do, and why.
+
+## User stories
+
+- As a <who>, I want <what> so that <why>.
+
+## Screens and states
+
+For each screen: what it's for, what it shows, and its loading, empty, error and success states.
+
+## Behavior and rules
+
+Business rules, validation, limits and edge cases. For stored data: the keys, values and types, identical on every platform.
+
+## Acceptance criteria
+
+Testable and platform-neutral. Each platform's tests put these IDs in their names.
+
+- AC-feature-id-1: ...
+- AC-feature-id-2: ...
+
+## Copy
+
+New or changed keys in contracts/strings.
+
+## Platform notes
+
+Where the platforms intentionally differ (navigation chrome, controls, gestures), and anything platform-only.
+
+## Test IDs
+
+- `feature.element`: ...
+
+## Assumptions and open questions
+
+- Assumption: ...

package/template/.gemini/settings.json

@@ -0,0 +1,5 @@
+{
+  "context": {
+    "fileName": ["AGENTS.md"]
+  }
+}

package/template/.github/dependabot.yml

@@ -0,0 +1,18 @@
+# Keeps each app's dependencies current. geeknative itself is an npm dev dependency,
+# so framework releases arrive here too (then run `make gen` and `make check`).
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      tanstack:
+        patterns: ["@tanstack/*"]
+  - package-ecosystem: gradle
+    directory: /apps/android
+    schedule:
+      interval: weekly
+    groups:
+      androidx:
+        patterns: ["androidx.*"]

package/template/AGENTS.md

@@ -0,0 +1,97 @@
+<!-- geeknative:begin (managed by geeknative: replaced on upgrade. Add your own rules under "Project rules" at the end.) -->
+# How to work in this repo
+
+This repo is **one product, built three times, natively**: iOS (SwiftUI), Android (Kotlin + Jetpack Compose) and web (React + TanStack Start). The apps share no code. They behave the same because every change goes through shared docs and contracts first, and you keep all three in step.
+
+## 1. Every request is for all three apps
+
+Unless the user names a platform ("on Android, ...") or the spec marks something as platform-only, a request is done only when iOS, Android **and** web all do it.
+
+## 2. Triage first, and say it in one line
+
+Before changing anything, decide what kind of request it is. State it as the first line of your reply, so the user can correct you early:
+
+> **Feature:** notes list → spec/features/notes.md, strings · iOS, Android, Web
+
+| The request...                                      | Type              | Update first                                             | Playbook                                    |
+|-----------------------------------------------------|-------------------|----------------------------------------------------------|---------------------------------------------|
+| describes an app, or changes what it is or who it's for | Product       | PRODUCT.md, DESIGN.md, spec/navigation.md, feature specs | .geeknative/playbooks/product.md            |
+| adds a screen, flow or capability                   | Feature           | a new `spec/features/<id>.md`                            | .geeknative/playbooks/feature.md            |
+| changes how something existing behaves              | Behavior change   | that feature's spec                                      | .geeknative/playbooks/feature.md            |
+| changes the look and feel                           | Design            | DESIGN.md and/or contracts/tokens.json                   | .geeknative/playbooks/design.md             |
+| changes wording only                                | Copy              | contracts/strings/*.json, then `make gen`                | none                                        |
+| reports something broken                            | Bug               | the spec, only if it was silent or wrong                 | .geeknative/playbooks/bug.md                |
+| names one platform                                  | Platform-specific | the feature's "Platform notes", if users can see it      | .geeknative/playbooks/platform-specific.md  |
+| is about tooling, dependencies, builds or refactoring | Engineering     | nothing                                                  | .geeknative/playbooks/engineering.md        |
+| asks a question                                     | Question          | nothing: answer it, don't edit files                     | none                                        |
+
+- A request can be several types at once (a feature usually adds copy too).
+- Keep it proportional: small tweaks don't need new spec files. Update a doc only when what it says changes.
+- If the user says "plan", "spec only" or "don't build yet", stop after updating the docs.
+
+## 3. Where things live
+
+| What | Source of truth |
+|---|---|
+| What the product is, who it's for, glossary | PRODUCT.md |
+| Visual language, components, what adapts per platform | DESIGN.md |
+| How each feature behaves, with acceptance criteria | `spec/features/<id>.md` (start from .geeknative/templates/feature.md) |
+| Screens and routes | spec/navigation.md |
+| Decisions and assumptions, dated | spec/decisions.md |
+| App name, ID and version | contracts/app.json |
+| Colors, spacing, radii and type | contracts/tokens.json |
+| All user-facing text | `contracts/strings/<locale>.json` |
+| Icons (SF Symbols, Material, Lucide) | contracts/icons.json |
+| Which platform has what | feature front matter → `make parity` → spec/parity.md |
+
+`make gen` compiles contracts/ into each app (`Generated/`, `generated/`, `generated_*.xml`, `Identity.xcconfig`, `identity.properties`). Never edit generated files: change the contract and regenerate.
+
+## 4. The loop
+
+1. **Update the source of truth** (section 3).
+2. **Regenerate** with `make gen` if contracts changed.
+3. **Implement on each platform.** Before editing under `apps/<platform>/`, read `apps/<platform>/AGENTS.md`.
+   - If you can run sub-agents in parallel, give each platform its own, with the spec path, the acceptance criteria IDs and what changed in contracts/. Only you, the lead, edit `spec/`, `contracts/`, PRODUCT.md and DESIGN.md; platform agents report gaps back to you.
+   - Otherwise, do the platforms one after another.
+4. **Verify** with `make check-ios`, `make check-android` and `make check-web` (or `make check` for everything). Fix until they pass.
+5. **Record** each platform's status in the feature's front matter, then run `make parity`.
+6. **Report** one line per platform (done, partial or skipped, and why), the checks you ran, and any assumptions you made.
+
+## 5. Keeping the apps aligned
+
+- **Build from the spec, not by porting.** Don't translate another app's code. If you had to read another app's code to know how something should behave, the spec has a gap: fix the spec first.
+- **Same names everywhere.** A feature `notes` is `NotesScreen`, `NotesViewModel` and `NotesRepository` in every app, in each app's notes feature folder. One search finds all three.
+- **Same IDs everywhere.** Test IDs (`notes.addButton`), storage keys and stored values match across apps.
+- **Tests name acceptance criteria.** Put the ID (for example `AC-notes-2`) in each test's name, so `make parity` can show coverage.
+- **Native, not identical.** Features, flows, data, copy and brand match. Navigation chrome, controls, gestures and system conventions follow each platform. DESIGN.md says which is which.
+- **One feature at a time.** Finish a feature on every platform before starting the next.
+- **Spec changes ripple.** If building one platform changes the spec, recheck the platforms you already did.
+- **No backend yet.** Features read and write through a repository interface with local implementations. When a backend arrives, only the repositories change.
+
+## 6. Ask or assume
+
+Ask only when a wrong guess is expensive to undo: the data model, the navigation structure, deleting features or data, or anything irreversible. Otherwise pick the conventional option, note it under "Assumptions" in the spec (and in spec/decisions.md if it affects more than one feature), and mention it in your report.
+
+## 7. Done means
+
+- The docs and contracts describe the new behavior.
+- `make gen` leaves no changes.
+- Checks pass for every platform you touched.
+- Each platform's status is recorded and spec/parity.md is current.
+- Anything left undone is in your report, with the reason.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `make doctor` | Checks Xcode, the Android SDK, Java and Node (`make doctor FIX=1` installs what it can) |
+| `make gen` | Regenerates app code from contracts/ |
+| `make check` | Validates contracts, then builds and tests all three apps |
+| `make check-ios`, `make check-android`, `make check-web` | One app; full logs go to .geeknative/logs/ |
+| `make run-ios`, `make run-android`, `make run-web` | Builds and launches one app |
+| `make parity` | Updates spec/parity.md |
+<!-- geeknative:end -->
+
+## Project rules
+
+<!-- Your own rules go here. They override the defaults above, and geeknative upgrades never touch them. -->

package/template/CLAUDE.md

@@ -0,0 +1,9 @@
+@AGENTS.md
+
+<!-- geeknative:begin (managed by geeknative: replaced on upgrade) -->
+## Claude Code
+
+- When a change touches more than one app, hand the platform work to the `ios-engineer`, `android-engineer` and `web-engineer` subagents in parallel (all three in one message). Give each the spec path, the acceptance criteria IDs and what changed in contracts/. You stay the lead and own spec/, contracts/, PRODUCT.md and DESIGN.md.
+- A hook runs `make gen` whenever you edit a file in contracts/, and reports errors in the contract right away.
+- A stop hook reminds you once if a turn changed some apps but not the others.
+<!-- geeknative:end -->

package/template/DESIGN.md

@@ -0,0 +1,65 @@
+# Design
+
+<!--
+How the app looks and feels on every platform. Your coding agent updates this when you ask for
+design changes. Token values live in contracts/tokens.json; this file explains how they're used.
+-->
+
+## Direction
+
+_Not described yet. Describe the look you want (for example "calm and minimal" or "bold and playful") and your coding agent will set colors, type and spacing to match._
+
+## Same everywhere, native where it counts
+
+| Same on every platform | Native to each platform |
+|---|---|
+| Features, flows and data | Navigation chrome (navigation bar, top app bar, site header) |
+| Copy (contracts/strings) | Controls: pickers, switches, radio lists, segmented controls |
+| Colors, spacing, radii and type scale (contracts/tokens.json) | Gestures, haptics and transitions |
+| Icons by meaning (contracts/icons.json) | Icon artwork: SF Symbols, Material icons, Lucide |
+| Screen structure and content order | Sheets, dialogs and menus |
+| Accessibility labels and test IDs | System font (SF Pro, Roboto, the browser's system font) |
+
+## Tokens
+
+Defined in contracts/tokens.json and compiled into each app by `make gen`.
+
+| Token | iOS | Android | Web (Tailwind) |
+|---|---|---|---|
+| Color `primary` | `AppColors.primary` | `AppTheme.colors.primary` | `bg-primary`, `text-primary` |
+| Color `onPrimary` | `AppColors.onPrimary` | `AppTheme.colors.onPrimary` | `text-on-primary` |
+| Spacing `md` | `AppSpacing.md` | `AppSpacing.md` | `p-md`, `gap-md` |
+| Radius `lg` | `AppRadius.lg` | `AppRadius.lg` | `rounded-lg` |
+| Type `title` | `AppTypography.title` | `AppTypography.title` | `text-title` |
+
+**Color roles.** Every color has a light and a dark value. Add new colors by role (what they're for), not by hue.
+
+- `background` / `onBackground`: screens.
+- `surface` / `onSurface`: cards and grouped content on a screen.
+- `surfaceVariant` / `onSurfaceVariant`: subtle fills and secondary text.
+- `primary` / `onPrimary`: the brand color, for primary actions and selection.
+- `outline`: borders and dividers.
+- `error` / `onError`: errors and destructive actions.
+
+**Type roles.** `display`, `headline`, `title`, `body`, `label`, `caption`. On iOS each maps to a Dynamic Type style; on Android and web, sizes scale with the user's font size setting.
+
+**Fonts.** The apps use each platform's system font. Codegen doesn't support custom fonts yet.
+
+## Components
+
+How each platform builds the shared patterns. Add a row whenever a new pattern appears.
+
+| Pattern | iOS | Android | Web |
+|---|---|---|---|
+| Screen | Screen in a `NavigationStack`, with a navigation title | `Scaffold` with a `TopAppBar` | Page in the app shell (header and main) |
+| Settings or form | `Form` with sections | Column with section headers | Sections in cards |
+| Single choice | Inline `Picker` (checkmarks) | Radio buttons | Radio group |
+| Card | `AppColors.surface` fill, `AppRadius.lg` corners | `Surface` in `AppTheme.colors.surface`, `AppRadius.lg` corners | `bg-surface rounded-lg` |
+| Primary action | `.borderedProminent` button | `Button` | `button` with `bg-primary text-on-primary` |
+
+## Accessibility
+
+- Support Dynamic Type (iOS), font scaling (Android) and browser zoom (web).
+- Every icon-only button has a label from contracts/strings.
+- Touch targets are at least 44 pt on iOS and 48 dp on Android.
+- Text meets WCAG AA contrast (4.5:1 for body text) in light and dark mode.

package/template/Makefile

@@ -0,0 +1,6 @@
+# Framework commands (doctor, gen, check, run-*, parity) come from geeknative.
+include .geeknative/framework.mk
+
+.DEFAULT_GOAL := help
+
+# Add your own targets below.

package/template/PRODUCT.md

@@ -0,0 +1,40 @@
+# Product
+
+<!--
+What the app is and who it's for. Your coding agent fills this in when you describe your app,
+and keeps it current as the product changes. Keep it short: details belong in spec/features/.
+-->
+
+## In one sentence
+
+_Not described yet. Tell your coding agent what you want to build._
+
+## Who it's for
+
+_Not described yet._
+
+## Features
+
+| Feature | Spec | Summary |
+|---|---|---|
+| Home | [spec/features/home.md](spec/features/home.md) | Starter screen with a welcome card |
+| Settings | [spec/features/settings.md](spec/features/settings.md) | Appearance (System, Light, Dark) and app version |
+
+## Platforms
+
+| Platform | Built with | Minimum |
+|---|---|---|
+| iOS | SwiftUI | iOS 17 |
+| Android | Kotlin, Jetpack Compose | Android 7.0 (API 24) |
+| Web | React, TanStack Start | Safari 16.4, Chrome 111, Firefox 128 |
+
+## Glossary
+
+Domain terms, defined once. Code uses these exact names on every platform.
+
+| Term | Meaning |
+|---|---|
+
+## Out of scope
+
+_Nothing yet._

package/template/README.md

@@ -0,0 +1,28 @@
+# {{APP_NAME}}
+
+Native iOS, Android and web apps built from one spec by your coding agent, using [geeknative](https://www.npmjs.com/package/geeknative).
+
+## Get started
+
+1. `make doctor` checks Xcode, the Android SDK, Java and Node. `make doctor FIX=1` installs what it can.
+2. `make check` builds and tests all three apps.
+3. Open this folder in your coding agent (Claude Code, Codex, Cursor, Gemini CLI, ...) and describe what you want to build.
+
+## Run the apps
+
+| Command | Opens |
+|---|---|
+| `make run-ios` | The iOS app in a simulator |
+| `make run-android` | The Android app on an emulator or connected device |
+| `make run-web` | The web app at http://localhost:3000 |
+
+## What's where
+
+| Path | Contents |
+|---|---|
+| AGENTS.md | Instructions every coding agent follows |
+| PRODUCT.md, DESIGN.md, spec/ | What the app does and how it looks |
+| contracts/ | App identity, design tokens, copy and icons, compiled into each app by `make gen` |
+| apps/ios, apps/android, apps/web | The three native apps |
+
+Run `make` to see every command.

package/template/_gitignore

@@ -0,0 +1,33 @@
+# Dependencies
+node_modules/
+
+# geeknative logs
+.geeknative/logs/
+
+# iOS
+apps/ios/.build/
+xcuserdata/
+*.xcuserstate
+
+# Android
+apps/android/.gradle/
+apps/android/.kotlin/
+apps/android/build/
+apps/android/app/build/
+apps/android/local.properties
+apps/android/.idea/
+*.iml
+.cxx/
+
+# Web
+apps/web/dist/
+apps/web/.output/
+apps/web/.tanstack/
+apps/web/.nitro/
+apps/web/.vinxi/
+
+# OS and editors
+.DS_Store
+.env
+.env.*
+!.env.example

package/template/apps/android/AGENTS.md

@@ -0,0 +1,66 @@
+<!-- geeknative:begin (managed by geeknative: replaced on upgrade. Add your own rules under "Project rules" at the end.) -->
+# Android app (Kotlin + Jetpack Compose)
+
+Read the root AGENTS.md first. This file covers how the Android app is built.
+
+## Stack
+
+- Kotlin and Jetpack Compose with Material 3, Android 7.0 (API 24) and later (Navigation 3's minimum). Compiles against API 37.
+- Navigation 3, ViewModel with StateFlow, Kotlin coroutines, DataStore.
+- Dependencies are wired by hand in `AppContainer`: no DI framework.
+- AGP 9 with built-in Kotlin. Gradle downloads JDK 21 for the build (gradle/gradle-daemon-jvm.properties).
+- JUnit and kotlinx-coroutines-test for unit tests.
+
+## Layout
+
+```
+apps/android/
+  gradle/libs.versions.toml      All dependency versions
+  app/build.gradle.kts           Reads app/identity.properties (generated) for the app ID and version
+  app/src/main/kotlin/app/
+    App.kt, MainActivity.kt      Creates AppContainer; applies the theme and appearance
+    core/                        AppContainer, navigation/ (Route, AppNavigation), designsystem/ (AppTheme, AppCard)
+    features/<name>/             <Name>Screen.kt, <Name>ViewModel.kt, <Name>Repository.kt, models
+    generated/                   From contracts/ by `make gen`. Never edit.
+  app/src/main/res/              values/generated_*.xml are generated; everything else is yours
+  app/src/test/kotlin/app/       Unit tests, named after acceptance criteria
+```
+
+The Kotlin package is always `app`. The app's identity is its application ID (from contracts/app.json), so renaming the app never moves code.
+
+## Patterns
+
+Same names and responsibilities as the iOS and web apps.
+
+| Concept | Android |
+|---|---|
+| Screen | `@Composable fun NotesScreen(...)` in features/notes/, plus a stateless `NotesContent` for previews |
+| State and actions | `NotesViewModel : ViewModel()` exposing `uiState: StateFlow<NotesUiState>` and action functions |
+| Data | `interface NotesRepository`, plus implementations such as `DataStoreNotesRepository` and `InMemoryNotesRepository` |
+| Dependencies | `AppContainer` from `LocalAppContainer.current`; ViewModels are created with `viewModel { NotesViewModel(container.notesRepository) }` |
+| Navigation | Add a `Route` object and an `entry<Route.Notes>` in AppNavigation; push with `backStack.add(Route.Notes)` |
+| Copy | `stringResource(R.string.notes_empty_title)` (generated from contracts/strings) |
+| Colors, spacing, radii, type | `AppTheme.colors.primary`, `AppSpacing.md`, `AppRadius.lg`, `AppTypography.title` |
+| Icons | `Icon(AppIcons.settings, contentDescription = ...)` (generated) |
+| Test IDs | `Modifier.testTag("notes.addButton")` |
+
+Follow features/settings as the reference implementation.
+
+## Rules
+
+- Never hardcode user-facing text, colors or spacing. Add them to contracts/ and run `make gen`.
+- Prefer native Material 3 components and Android conventions: top app bars, the system back gesture, snackbars, bottom sheets. DESIGN.md says what must match the other platforms.
+- Collect flows with `collectAsStateWithLifecycle()`. Keep screens stateless below the ViewModel so they can be previewed.
+- Support font scaling, dark mode and TalkBack: icon-only buttons need a content description from strings.
+- Name tests after acceptance criteria: ``fun `AC-notes-2 ...`()``.
+
+## Commands
+
+- `make check-android`: builds the app and runs the unit tests. Full log: .geeknative/logs/android.log.
+- `make run-android`: installs and launches the app on a running emulator or connected device.
+- Open apps/android in Android Studio to use previews and the layout inspector.
+<!-- geeknative:end -->
+
+## Project rules
+
+<!-- Your Android-specific rules. They override the defaults above, and geeknative upgrades never touch them. -->

package/template/apps/android/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/apps/android/app/build.gradle.kts

@@ -0,0 +1,68 @@
+import java.util.Properties
+
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.compose)
+    alias(libs.plugins.kotlin.serialization)
+}
+
+// App name, ID and version come from contracts/app.json (generated by `make gen`).
+val identity = Properties().apply {
+    load(providers.fileContents(layout.projectDirectory.file("identity.properties")).asText.get().reader())
+}
+
+android {
+    // The Kotlin package stays "app" in every project; the app's identity is applicationId.
+    namespace = "app"
+    compileSdk {
+        version = release(37)
+    }
+
+    defaultConfig {
+        applicationId = identity.getProperty("applicationId")
+        minSdk = 24
+        targetSdk = 37
+        versionCode = identity.getProperty("versionCode").toInt()
+        versionName = identity.getProperty("versionName")
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    buildFeatures {
+        compose = true
+    }
+
+    testOptions {
+        unitTests.isReturnDefaultValues = true
+    }
+}
+
+dependencies {
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.activity.compose)
+    implementation(platform(libs.androidx.compose.bom))
+    implementation(libs.androidx.compose.ui)
+    implementation(libs.androidx.compose.ui.tooling.preview)
+    implementation(libs.androidx.compose.material3)
+    implementation(libs.androidx.compose.material.icons.core)
+    implementation(libs.androidx.lifecycle.runtime.compose)
+    implementation(libs.androidx.lifecycle.viewmodel.compose)
+    implementation(libs.androidx.lifecycle.viewmodel.navigation3)
+    implementation(libs.androidx.navigation3.runtime)
+    implementation(libs.androidx.navigation3.ui)
+    implementation(libs.androidx.datastore.preferences)
+    implementation(libs.kotlinx.serialization.core)
+    debugImplementation(libs.androidx.compose.ui.tooling)
+
+    testImplementation(libs.junit)
+    testImplementation(libs.kotlinx.coroutines.test)
+}

package/template/apps/android/app/identity.properties

@@ -0,0 +1,4 @@
+# GENERATED by geeknative from contracts/app.json. Do not edit: change the contract, then run `make gen`.
+applicationId=com.example.geeknative
+versionName=1.0.0
+versionCode=1