agentic-team 0.0.0-stage → 6.1.0

package/template/.orchestra/stacks/mobile-expo/setup.sh

@@ -0,0 +1,470 @@
+#!/usr/bin/env bash
+# Expo / React Native.
+#
+# No styling framework and no UI library. Tokens are a typed module and
+# components are built from React Native primitives, so the kit owes nothing
+# to a third party's release schedule.
+set -euo pipefail
+
+DIR="${1:?usage: setup.sh <target-dir>}"
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../_lib" && pwd)"
+# shellcheck source=../_lib/common.sh
+source "$LIB/common.sh"
+
+# --no-agents-md: create-expo-app writes its own CLAUDE.md and
+# .claude/settings.json, which would collide with the stack's pack.
+log "scaffolding expo into $DIR"
+# --yes and </dev/null together: inside an existing git repository the CLI
+# asks whether to skip `git init`, and with a pipe for stdin it waits for an
+# answer that never comes. A create tool must never be able to block a
+# scaffold — closing stdin turns a missed prompt into an error instead of a
+# hang.
+npx --yes create-expo-app@latest "$DIR" \
+  --yes --template blank-typescript --no-agents-md --no-install </dev/null
+
+assert_scaffolded "$DIR"
+cd "$DIR"
+
+setup_yarn
+yarn_install
+
+setup_typescript
+setup_biome
+setup_node_pin
+setup_typecheck_script
+
+# Native modules — expo install keeps them on SDK-compatible versions.
+expo_install @sentry/react-native posthog-react-native
+# Test deps, in the shape today's packages actually want. Verified against a
+# real scaffold — each of these was a failure before it was a comment:
+#  - jest is neither a dependency nor a peer of jest-expo, so without it
+#    `npm test` is "jest: command not found"
+#  - RNTL 14 peers on `test-renderer`, NOT the deprecated react-test-renderer.
+#    react-test-renderer@latest wants a react newer than the SDK pins and npm
+#    refuses the whole tree.
+#  - @react-native/jest-preset IS required, but only at the version matching
+#    the installed react-native. At @latest it drags in a react-dom newer than
+#    the SDK's react and the whole tree is rejected. npm's flat hoisting hid
+#    this; yarn does not hoist, so the preset must be declared.
+expo_install --dev jest-expo
+#  - jest is pinned to the 29 line because jest-expo depends on jest 29
+#    packages throughout. jest@latest installs 30, and the resulting
+#    jest-runtime 30 / jest-mock 29 split fails every suite with
+#    "this._moduleMocker.clearMocksOnScope is not a function".
+add_latest --dev "jest@29" test-renderer @testing-library/react-native
+# @types/jest is on the SDK table (57 wants 29.5.14, not the registry's 30),
+# so it goes through expo install like every other managed package.
+expo_install --dev @types/jest
+
+# Match the preset to the installed react-native rather than taking @latest.
+RN_VERSION="$(node -e 'const d=require("./package.json").dependencies;process.stdout.write(String(d["react-native"]||"").replace(/[^0-9.]/g,""))')"
+if [ -n "$RN_VERSION" ]; then
+  add_latest --dev "@react-native/jest-preset@${RN_VERSION}"
+else
+  warn "could not read react-native version — install @react-native/jest-preset manually"
+fi
+pkg_set scripts.test="jest --passWithNoTests" scripts.test:watch="jest --watch"
+pkg_set jest.preset="jest-expo"
+
+log "writing design system skeleton"
+mkdir -p src/design/helpers
+
+cat > src/design/tokens.ts <<'TS'
+/**
+ * Design tokens. Populated from the Claude Design source before any
+ * component is written. Colour is one axis of several — do not stop there.
+ *
+ * `as const` is deliberate: it makes every value a literal type, so a typo
+ * in a component is a compile error rather than a silent undefined.
+ */
+export const tokens = {
+  spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 },
+  radius: { control: 8, surface: 12, pill: 999 },
+  fontSize: { caption: 12, body: 16, title: 20, display: 28 },
+  fontWeight: { regular: "400", medium: "500", bold: "700" },
+  duration: { fast: 120, normal: 240 },
+  // Minimum touch target on both platforms. Not negotiable.
+  hitTarget: 44,
+} as const;
+
+/** Raw palette. Components never reference these — they use the theme. */
+export const palette = {
+  white: "#ffffff",
+  black: "#000000",
+  neutral50: "#f9fafb",
+  neutral900: "#111827",
+  brand500: "#2563eb",
+  danger500: "#dc2626",
+} as const;
+TS
+
+cat > src/design/theme.ts <<'TS'
+import { palette } from "./tokens";
+
+/**
+ * Semantic layer. Components reference these names, never the palette, so
+ * a theme change stays a one-file change.
+ */
+export type Theme = {
+  surface: string;
+  onSurface: string;
+  accent: string;
+  danger: string;
+};
+
+export const lightTheme: Theme = {
+  surface: palette.white,
+  onSurface: palette.neutral900,
+  accent: palette.brand500,
+  danger: palette.danger500,
+};
+
+export const darkTheme: Theme = {
+  surface: palette.neutral900,
+  onSurface: palette.neutral50,
+  accent: palette.brand500,
+  danger: palette.danger500,
+};
+TS
+
+cat > src/design/ThemeProvider.tsx <<'TSX'
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { useColorScheme } from "react-native";
+import { darkTheme, lightTheme, type Theme } from "./theme";
+
+export type ThemeName = "light" | "dark" | "system";
+
+const ThemeContext = createContext<Theme>(lightTheme);
+
+/** Read the active theme. Components call this instead of importing colours. */
+export const useTheme = (): Theme => useContext(ThemeContext);
+
+export function ThemeProvider({
+  children,
+  name = "system",
+}: {
+  children: ReactNode;
+  name?: ThemeName;
+}) {
+  const system = useColorScheme();
+  const theme = useMemo(() => {
+    const resolved = name === "system" ? (system ?? "light") : name;
+    return resolved === "dark" ? darkTheme : lightTheme;
+  }, [name, system]);
+
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+}
+TSX
+
+cat > src/design/types.ts <<'TS'
+// Shared design-system types only. Nothing app-specific, no business logic.
+export type Size = "sm" | "md" | "lg";
+export type Variant = "primary" | "secondary" | "danger";
+TS
+
+cat > src/design/index.ts <<'TS'
+export * from "./tokens";
+export * from "./theme";
+export * from "./types";
+export { ThemeProvider, useTheme } from "./ThemeProvider";
+TS
+
+install_pre_commit_gate
+# Jest here, not vitest — setup_coverage writes a vitest config, which would
+# be dead weight in this app.
+setup_integrations_dir
+
+setup_coverage_jest
+setup_mutation
+
+# The two commands that see what typecheck and jest cannot: a native module
+# off the SDK's compatibility table. This is the class of defect that passes
+# every JS test and then fails on a device.
+# Installed rather than run through npx: CI should not resolve a different
+# version of the checker on every run. add_latest, not expo_install — the
+# checker is not on the SDK table, and routing it through `expo install`
+# makes the CLI re-parse its own argv and fail on "install" as a directory.
+add_latest --dev expo-doctor
+pkg_set scripts.doctor="expo-doctor && expo install --check"
+# A real build, without EAS or a signing identity. `expo export` runs Metro
+# over the whole graph exactly as a release bundle does, so an import that
+# only resolves in dev, a missing asset, or a native module the SDK does not
+# ship all fail here — none of which tsc, lint or jest can see. CI has no
+# device, so this is the only thing standing between a green suite and an app
+# that cannot start.
+pkg_set scripts.build="expo export --platform all --output-dir .expo-export"
+grep -q '^\.expo-export/' .gitignore 2>/dev/null || printf '\n# expo export (build output)\n.expo-export/\n' >> .gitignore
+
+# Our own API, faked at the network layer. Mocking the fetch wrapper instead
+# would leave the wrapper — the thing that breaks when the API changes —
+# untested. msw ships react-native export conditions.
+add_latest --dev msw
+
+# Pin the application id before anything reads it.
+#
+# Left unset, `expo prebuild` derives it from the machine's username — the
+# developer gets com.sulhadin.mobile and CI gets com.runner.mobile, for the
+# same commit. Every id-addressed thing downstream then points at an app that
+# does not exist on the device it is running against: maestro flows, push
+# certificates, deep links, store uploads.
+#
+# com.example is deliberately not a plausible id. It has to be replaced with
+# the real organisation identifier before any release, and it should be
+# obvious that it has not been.
+node -e '
+  const fs = require("fs");
+  const f = ["app.json", "app.config.json"].find((x) => fs.existsSync(x));
+  if (!f) process.exit(0);
+  const doc = JSON.parse(fs.readFileSync(f, "utf8"));
+  const expo = (doc.expo = doc.expo || {});
+  const id = `com.example.${(expo.slug || "app").replace(/[^a-z0-9]/gi, "")}`;
+  expo.android = { ...(expo.android || {}) };
+  expo.ios = { ...(expo.ios || {}) };
+  if (!expo.android.package) expo.android.package = id;
+  if (!expo.ios.bundleIdentifier) expo.ios.bundleIdentifier = id;
+  fs.writeFileSync(f, JSON.stringify(doc, null, 2) + "\n");
+  console.log("  [+] application id pinned to " + expo.android.package);
+'
+warn "the application id is a placeholder — set ios.bundleIdentifier and"
+warn "android.package to your real organisation id before any release."
+
+# Sentry's Xcode build phase runs sentry-cli to upload source maps, and with
+# no organisation configured it does not warn — it fails the build with
+# exit 65. A freshly scaffolded app therefore cannot build for iOS at all,
+# while Android builds fine, so nothing catches it until someone opens Xcode.
+#
+# sentry-xcode.sh gates on a shell variable in the build phase's own
+# environment:  if [ "$SENTRY_DISABLE_AUTO_UPLOAD" != true ]
+# It never sources a dotenv, and ios/.xcode.env is regenerated by every
+# `expo prebuild`, so the variable has to be set where the build is invoked.
+#
+# Not a blanket disable: with real credentials present the upload still runs.
+# Symbols remain required before release — see
+# .claude/rules/observability.orchestra.md. This only stops a build that has
+# no credentials from failing because of it.
+SENTRY_GUARD='SENTRY_DISABLE_AUTO_UPLOAD=$([ -n "$SENTRY_AUTH_TOKEN" ] && echo false || echo true)'
+# LANG for the same reason e2e-ios.sh sets it, and it belongs here too:
+# `expo run:ios` shells out to CocoaPods, which reads the Podfile through
+# ruby's default external encoding. With no UTF-8 locale that is US-ASCII and
+# pod install dies inside String#unicode_normalize — after which xcodebuild
+# reports "the sandbox is not in sync with the Podfile.lock", which names
+# neither the cause nor the fix. The e2e path was guarded and the path a
+# developer actually types was not.
+IOS_LOCALE='LANG=${LANG:-en_US.UTF-8}'
+pkg_set "scripts.ios=${IOS_LOCALE} ${SENTRY_GUARD} expo run:ios" \
+        "scripts.android=${SENTRY_GUARD} expo run:android"
+log "sentry: symbol upload runs only when SENTRY_AUTH_TOKEN is present"
+
+# The launch flow has to assert something only this app can render. Without a
+# marker it can only assert "some element is visible", which React Native's
+# red bundle-error screen satisfies — the one failure the check exists to
+# catch.
+#
+# The root view owns the marker, so the assertion holds no matter what the
+# screen becomes. setup_maestro refuses to write flows without it.
+cat > App.tsx <<'TSX'
+import { StatusBar } from "expo-status-bar";
+import { StyleSheet, Text, View } from "react-native";
+
+export default function App() {
+	// testID="app-root" is load-bearing: .maestro/launch.yaml asserts it to
+	// prove this app's tree actually mounted. Keep it on whatever the root
+	// becomes — a navigator, a provider tree — or the launch check weakens
+	// to "something is on screen", which a bundle-error screen satisfies.
+	return (
+		<View style={styles.container} testID="app-root">
+			<Text>Open up App.tsx to start working on your app!</Text>
+			<StatusBar style="auto" />
+		</View>
+	);
+}
+
+const styles = StyleSheet.create({
+	container: {
+		flex: 1,
+		backgroundColor: "#fff",
+		alignItems: "center",
+		justifyContent: "center",
+	},
+});
+TSX
+log "App.tsx carries testID=app-root for the launch flow"
+
+setup_maestro
+
+# Expo's tsconfig sets an explicit types list, so jest globals are invisible
+# to tsc until "jest" is added to it.
+node -e "$JSONC_READ"'
+  const fs = require("fs");
+  const f = "tsconfig.json";
+  if (!fs.existsSync(f)) process.exit(0);
+  const c = readJsonc(f);
+  c.compilerOptions = { ...(c.compilerOptions || {}) };
+  c.compilerOptions.types = [...new Set([...(c.compilerOptions.types || []), "jest"])];
+  fs.writeFileSync(f, JSON.stringify(c, null, 2) + "\n");
+'
+
+# Not refresh_scaffold_deps: in an Expo app the SDK is the authority, not
+# the registry. setup_typescript installed typescript@latest, which the
+# SDK does not accept — this puts every managed package back on the table
+# and fails the scaffold if any of them is still off it.
+assert_expo_sdk_aligned
+
+# Format last: every generated file — the design skeleton, tailwind config
+# and the tsconfig edit above — lands after setup_biome ran, and an
+# unformatted scaffold is rejected by the gate this script just installed.
+yarn biome check --write . >/dev/null 2>&1 || true
+
+# ── e2e, as a script rather than only as CI steps ─────────────────────────
+# The workflow used to carry the build and the maestro run inline, which made
+# it unrunnable anywhere else: nobody could reproduce a red e2e locally, and
+# the orchestrator's own CI could only test a *copy* of those steps. A copy
+# that drifts proves nothing. One script, called by both.
+cat > e2e-ios.sh <<'E2E'
+#!/usr/bin/env bash
+# Build the app for a simulator and run the maestro flows against it.
+# Called by .github/workflows/mobile-e2e.yml and runnable by hand.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+# A debug e2e build has no Sentry credentials and must not fail for want of
+# them. Sentry's Xcode phase gates on this exact variable and kills the build
+# with exit 65 otherwise.
+export SENTRY_DISABLE_AUTO_UPLOAD="${SENTRY_DISABLE_AUTO_UPLOAD:-true}"
+
+# CocoaPods reads the Podfile through ruby's default external encoding. With
+# no locale set that is US-ASCII, and `pod install` dies inside
+# String#unicode_normalize with "Unicode Normalization not appropriate for
+# ASCII-8BIT" — then xcodebuild fails with the far less helpful "sandbox is
+# not in sync with the Podfile.lock".
+export LANG="${LANG:-en_US.UTF-8}"
+
+# maestro is a JVM application, and nothing else in this script needs a JDK.
+# Without one it dies on "Unable to locate a Java Runtime" after the build has
+# already been paid for.
+if [ -z "${JAVA_HOME:-}" ]; then
+  JAVA_HOME="$(/usr/libexec/java_home 2>/dev/null || true)"
+  [ -n "$JAVA_HOME" ] && export JAVA_HOME
+fi
+command -v java >/dev/null 2>&1 || [ -x "${JAVA_HOME:-}/bin/java" ] || {
+  echo "no JDK on PATH — maestro cannot run without one" >&2
+  exit 1
+}
+
+if ! command -v maestro >/dev/null 2>&1; then
+  if [ -x "$HOME/.maestro/bin/maestro" ]; then
+    PATH="$HOME/.maestro/bin:$PATH"; export PATH
+  else
+    echo "── installing maestro"
+    curl -fsSL https://get.maestro.mobile.dev | bash
+    PATH="$HOME/.maestro/bin:$PATH"; export PATH
+  fi
+fi
+
+echo "── native dependency check"
+yarn doctor
+
+# Two reasons this is not `run:ios --configuration Debug`, both reproduced on
+# a real machine. A debug build loads its JS from Metro, so the command stays
+# attached to the bundler and **never exits** — the job burns its timeout and
+# maestro never runs. And a debug build with no dev server opens on the red
+# error screen, which maestro's launch check happily passes.
+#
+# Release embeds the bundle; --no-bundler skips Metro entirely. Both flags are
+# the CLI's own, read from `expo run:ios --help`. Simulator builds are
+# unsigned, so no certificate is involved.
+echo "── build and install on a simulator"
+yarn expo run:ios --configuration Release --no-bundler
+
+echo "── maestro"
+maestro test .maestro
+E2E
+chmod +x e2e-ios.sh
+log "e2e-ios.sh (build + maestro, runnable by hand and from CI)"
+
+cat > e2e-android.sh <<'E2E'
+#!/usr/bin/env bash
+# Build the release APK, then drive it with maestro.
+#
+# Two phases, because the emulator is not ours to own: in CI the
+# android-emulator-runner action boots one and runs a script inside it, so the
+# build has to happen before that and the test inside it.
+#
+#   ./e2e-android.sh build   — doctor, prebuild, assembleRelease
+#   ./e2e-android.sh test    — install on the connected device and run maestro
+#   ./e2e-android.sh         — both, against whatever device is attached
+set -euo pipefail
+cd "$(dirname "$0")"
+
+export SENTRY_DISABLE_AUTO_UPLOAD="${SENTRY_DISABLE_AUTO_UPLOAD:-true}"
+
+APK="android/app/build/outputs/apk/release/app-release.apk"
+
+find_jdk() {
+  [ -n "${JAVA_HOME:-}" ] && [ -x "$JAVA_HOME/bin/java" ] && return 0
+  for candidate in "$(/usr/libexec/java_home -v 21 2>/dev/null || true)" \
+                   /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home \
+                   /usr/lib/jvm/temurin-21-jdk-amd64 \
+                   /usr/lib/jvm/java-21-openjdk-amd64; do
+    [ -n "$candidate" ] && [ -x "$candidate/bin/java" ] && { export JAVA_HOME="$candidate"; return 0; }
+  done
+  echo "no JDK 21 found — gradle and maestro both need one" >&2
+  exit 1
+}
+
+ensure_maestro() {
+  command -v maestro >/dev/null 2>&1 && return 0
+  if [ -x "$HOME/.maestro/bin/maestro" ]; then
+    PATH="$HOME/.maestro/bin:$PATH"; export PATH; return 0
+  fi
+  echo "── installing maestro"
+  curl -fsSL https://get.maestro.mobile.dev | bash
+  PATH="$HOME/.maestro/bin:$PATH"; export PATH
+}
+
+do_build() {
+  find_jdk
+  echo "── native dependency check"
+  yarn doctor
+
+  echo "── generate the native project"
+  yarn expo prebuild --platform android --no-install
+
+  # Release, not debug. A debug APK contains no JS bundle — it fetches one
+  # from Metro at launch — so on a machine with no dev server the app opens on
+  # the red "could not connect" screen. Maestro's launch check passes on that
+  # screen, which is worse than failing: the run goes green having proved
+  # nothing. Release embeds the bundle. Expo's template signs release with the
+  # debug key, so no keystore is needed.
+  echo "── build release APK"
+  (cd android && ./gradlew assembleRelease --no-daemon)
+  [ -f "$APK" ] || { echo "no APK at $APK after assembleRelease" >&2; exit 1; }
+}
+
+do_test() {
+  find_jdk
+  ensure_maestro
+  [ -f "$APK" ] || { echo "no APK at $APK — run './e2e-android.sh build' first" >&2; exit 1; }
+
+  echo "── install"
+  adb install -r "$APK"
+
+  echo "── maestro"
+  maestro test .maestro
+}
+
+case "${1:-all}" in
+  build) do_build ;;
+  test)  do_test ;;
+  all)   do_build; do_test ;;
+  *) echo "usage: $0 [build|test]" >&2; exit 2 ;;
+esac
+E2E
+chmod +x e2e-android.sh
+log "e2e-android.sh (build + maestro, two phases so CI can own the emulator)"
+
+assert_verification_scripts
+assert_scaffold_clean
+log "mobile-expo ready in $DIR"
+warn "e2e flows are in .maestro/ — fill in core-flow.yaml before trusting the suite."
+warn "The maestro CLI installs separately: curl -fsSL https://get.maestro.mobile.dev | bash"

package/template/.orchestra/stacks/mobile-expo/stack.md

@@ -0,0 +1,141 @@
+# Mobile — Expo / React Native
+
+## Who you are
+
+You are two engineers at once, and both have to be satisfied:
+
+- a **senior frontend engineer** — component API design, state, render cost
+- a **senior mobile engineer** — platform conventions, touch targets, safe
+  areas, keyboard behavior, list performance, offline and slow networks
+
+Web habits that do not survive on a phone: hover states, tiny tap targets,
+unbounded lists, assuming a fast network, ignoring the notch. Catch these
+in your own work before review does.
+
+SOLID, KISS, YAGNI. No overengineering.
+
+## Structure
+
+Mirrors the web stacks deliberately — one mental model across the repo.
+
+```
+src/
+├── design/                 # the UI kit. no business logic. ever.
+│   ├── tokens.ts           # raw scales
+│   ├── theme.ts            # semantic layer
+│   ├── ThemeProvider.tsx
+│   ├── types.ts
+│   ├── helpers/
+│   ├── index.ts
+│   └── Button/
+│       ├── Button.tsx
+│       ├── Button.test.tsx
+│       ├── types.ts
+│       └── index.ts
+└── ...
+```
+
+Every component gets its own folder: component, tests, types, `index.ts`.
+
+`src/design/` holds nothing that is not design.
+
+## Styling — no framework
+
+There is no Tailwind, no NativeWind, and no UI library here. Styling is
+`StyleSheet.create` over a typed token module.
+
+That is a deliberate trade. A styling framework on React Native buys terse
+class strings and costs a build-time transform, a peer-version treadmill,
+and a layer between you and the platform when something renders wrong. At
+the size of one design system it does not pay for itself.
+
+```
+src/design/
+├── tokens.ts        # spacing, radius, type scale, motion, hit targets
+├── theme.ts         # semantic names over the palette
+├── ThemeProvider.tsx
+├── types.ts
+└── index.ts
+```
+
+`tokens.ts` uses `as const`, so every value is a literal type and a typo in
+a component is a compile error rather than a silent `undefined`.
+
+Components call `useTheme()`. They never import the palette directly — that
+is what keeps a theme change to one file.
+
+## No ready-made components
+
+The kit is built from React Native primitives — `Pressable`, `View`,
+`Text`, `FlatList`. No Paper, no NativeBase, no imported button.
+
+Platform primitives are the substrate, not a UI kit. Wrapping them in our
+own components is the job; installing someone else's opinion is not.
+
+## Order of work
+
+Tokens before components. Extract every axis from the design source —
+colour, spacing, typography, radii, elevation, motion — into `tokens.ts`,
+then map meaning onto them in `theme.ts`.
+
+A component with a hardcoded `#2563eb` or `padding: 13` is a bug.
+
+## Platform rules
+
+- Minimum touch target 44×44pt. Smaller is a defect, not a design choice.
+- Respect safe areas. Never assume a rectangular screen.
+- Long lists are virtualized. A `map()` over server data will jank.
+- Handle the keyboard: avoidance, dismissal, and the return key.
+- Every screen has a loading, empty, and error state. All three.
+- Test on both platforms. "Works on iOS" is half an answer.
+
+## Memory — the collector cannot end what you still hold
+
+React does not free a subscription for you, and the collector cannot free
+what a live closure still references. So:
+
+- **Every effect that starts something returns the function that stops
+  it.** `AppState`, `Dimensions`, `Keyboard`, notification and deep-link
+  listeners all return a subscription — `.remove()` it; `setInterval` →
+  `clearInterval`; a fetch → an `AbortController` aborted in the cleanup. The gate checks that the cleanup
+  exists; only you can check that it stops the right thing.
+- State that only grows is a leak with a UI. A list that appends on every
+  event and never trims, a map of every id ever seen — bound it, or key it
+  by what is on screen.
+- A closure created in render captures the render's state and is recreated
+  every render. That is by design; it becomes a cost when it is passed to a
+  memoized child or a long list. `.claude/rules/performance.orchestra.md`
+  says where that matters.
+- A module-level cache is process-lifetime. Give it a maximum and an
+  eviction rule, or it is the thing that grows with uptime.
+
+On a phone the budget is smaller and the collector is Hermes, not V8. A
+leaked screen is a leaked native view tree, and the OS kills the app when it
+notices — which reads as a crash with no stack trace.
+
+## Testing
+
+Coverage target is effectively total. The deciding rule:
+
+> If one of our functions calls into a third-party library, that function
+> has a test. When Dependabot bumps the library and behavior changes, the
+> test must fail.
+
+Tooling differs from web on purpose: `jest-expo` plus React Native Testing
+Library. Vitest browser mode drives real browsers, which React Native does
+not have.
+
+- Interaction tests are primary — press, focus, disabled, navigation.
+- Snapshots are secondary. Snapshot-only is untested.
+- E2E via Maestro, installed separately.
+
+## Accessibility
+
+`accessibilityRole`, `accessibilityLabel`, and `accessibilityState` on
+anything interactive. Test with VoiceOver and TalkBack. Respect the user's
+font scale — a layout that breaks at large text is broken.
+
+## Tooling
+
+Biome for lint and format. TypeScript strict with
+`noUncheckedIndexedAccess`.

package/template/.orchestra/stacks/mobile-ios-native/claude/commands/component.md

@@ -0,0 +1,12 @@
+Scaffold a new iOS design system component.
+
+Usage: `/ios:component {Name}`
+
+1. Load the `design-component` skill and follow it.
+2. Confirm every value has a token. Missing one? Add it to `Tokens.swift`
+   or the asset catalog first — never hardcode.
+3. Create `Sources/DesignSystem/{Name}/` and the matching test file.
+4. If the project needs a new target or setting, edit `project.yml` and run
+   `xcodegen generate`. Never touch the `.pbxproj`.
+5. Run the build and test via `xcodebuild`.
+6. Report the a11y checklist with each item checked or flagged.

package/template/.orchestra/stacks/mobile-ios-native/claude/skills/design-component/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: design-component
+description: "Author a SwiftUI component in the iOS design system — folder layout, tokens, snapshot and behavior tests, accessibility. Use for work under Sources/DesignSystem/."
+---
+
+# Authoring an iOS design system component
+
+## Folder
+
+```
+Sources/DesignSystem/{Name}/
+├── {Name}.swift
+└── {Name}Style.swift        # if it has variants
+Tests/DesignSystemTests/
+└── {Name}Tests.swift
+```
+
+## Before writing
+
+1. Does a token exist for every value you need? If not, add it to
+   `Tokens.swift` or the asset catalog first. Never hardcode a color,
+   radius, spacing, or duration.
+2. Does SwiftUI already provide this? Do not reimplement `Button` to change
+   its background — write a `ButtonStyle`.
+3. Does this view need to know anything about the product? If yes, it does
+   not belong in `DesignSystem/`.
+
+## API
+
+- Public initializers with sensible parameter names.
+- Variants as an enum, not a set of booleans that can contradict.
+- Accept a `@ViewBuilder` closure for content rather than a fixed `String`,
+  where a caller might reasonably want more.
+- Nothing `public` that does not need to be.
+
+## Tests
+
+Behavior first, snapshot second.
+
+- Snapshot in light, dark, and the largest Dynamic Type size.
+- Assert behavior separately — an action fires, a disabled control does not.
+- If the component wraps a dependency, test *our* wrapper so a version bump
+  that changes behavior turns the suite red.
+
+## Accessibility checklist
+
+- [ ] accessibility label present and meaningful
+- [ ] correct traits (`.isButton`, `.isHeader`, …)
+- [ ] value exposed where one applies (sliders, toggles)
+- [ ] VoiceOver order is sensible, not just complete
+- [ ] layout survives the largest Dynamic Type size
+- [ ] touch target at least 44x44pt
+- [ ] contrast holds in light and dark
+
+## Done means
+
+View, style, tests in all three configurations, and the a11y checklist —
+each item explicitly checked or flagged.