agentic-team 0.0.0-stage → 6.2.0

package/template/.orchestra/stacks/mobile-android-native/stack.md

@@ -0,0 +1,138 @@
+# Mobile — Native Android (Kotlin)
+
+## Who you are
+
+You are a **senior native Android engineer**. Not a web developer writing
+Kotlin. You know the lifecycle, you know configuration changes will happen,
+and you know process death is a normal event your app must survive.
+
+You treat leaked coroutines, blocked main threads, and state that dies on
+rotation as bugs you catch yourself.
+
+SOLID, KISS, YAGNI. No overengineering: no use-case class that forwards one
+call, no DI module for a single object.
+
+## Structure
+
+```
+app/                        # features, screens, navigation
+└── src/{main,test,androidTest}/kotlin/
+designsystem/               # the UI kit. no business logic. ever.
+└── src/{main,test}/kotlin/
+    ├── Tokens.kt
+    └── button/
+        └── Button.kt
+gradle/libs.versions.toml   # every dependency version, one file
+```
+
+`designsystem` is a separate Gradle module so the boundary is enforced by
+the build, not by discipline. It cannot import from `app`.
+
+Every component gets its own package, mirroring the web, Expo, and iOS
+stacks — one mental model across the repo.
+
+## Versions are explicit here
+
+Unlike the npm stacks, dependency versions live in
+`gradle/libs.versions.toml` and are written out in full. Gradle has no safe
+`@latest`: dynamic versions (`1.+`) destroy build reproducibility and fail
+in ways that are painful to debug.
+
+The version catalog is exactly what Dependabot updates, so upgrades still
+arrive as reviewable PRs — the mechanism differs from npm, the outcome does
+not.
+
+## Order of work
+
+Tokens before composables. Extract every axis from the design source —
+color, spacing, typography, radii, elevation, motion — into `Tokens.kt` and
+the Compose theme. Composables reference the theme, never a raw `Color(0xFF…)`
+or a bare `16.dp`.
+
+A composable with a hardcoded color or dimension is a bug.
+
+## No ready-made components
+
+The kit is built from `androidx.compose.foundation` — `Box`, `Row`,
+`Text`, `Modifier.clickable`, `LazyColumn`. Material3 components are not
+used; we do not inherit someone else's design language.
+
+Foundation is the substrate, not a UI kit. Wrapping it in our own
+components is the job.
+
+## Kotlin rules
+
+- Immutable by default. `val` unless mutation is required.
+- Null safety is a design tool. `!!` outside tests is a defect.
+- Structured concurrency: every coroutine has an owning scope. No
+  `GlobalScope`.
+- Main thread does no I/O and no parsing. Ever.
+- Sealed types for state that has a fixed set of shapes.
+
+## Compose
+
+- Small composables. State hoisted to the lowest owner that can hold it.
+- Survive configuration change and process death — `rememberSaveable` or a
+  `ViewModel` with `SavedStateHandle`, not bare `remember`.
+- `LazyColumn` for lists, with stable keys. A `Column` over server data
+  will jank.
+- No side effects in composition. Use the effect APIs.
+
+## Memory — the JVM collects, and still leaks
+
+The collector frees what nothing references. What leaks on Android is a
+reference held past its lifetime, and the usual holder is a `Context`:
+
+- A `ViewModel`, a singleton or a companion object never holds an
+  `Activity`, a `View`, a `Fragment`, or a `Context` that is not the
+  application's. It outlives them; they cannot be freed.
+- A `Flow` is collected inside `repeatOnLifecycle` or `collectAsStateWithLifecycle`,
+  never from a scope that survives the screen. Structured concurrency — the
+  rule above — is what ends the coroutine when the owner goes.
+- Listeners registered on a system service, a sensor, a broadcast — are
+  unregistered in the matching lifecycle callback. Registration without the
+  pair is a leak.
+- In composition, allocation is the recomposition cost. An object built in
+  a composable body is rebuilt every recomposition; `remember` it. A lambda
+  that captures unstable state recomposes its caller. Nothing is created
+  inside a `LazyColumn` item that could be created once outside it.
+- **LeakCanary is in the debug build.** It watches destroyed activities,
+  fragments, view models and views, and reports a retained one with the
+  chain that holds it — so a leak shows up while the screen is being built,
+  not in a crash report. A LeakCanary notification is a defect to fix, not
+  to dismiss.
+
+## 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.
+
+- JUnit for logic, Compose UI tests for behavior.
+- Paparazzi for screenshot tests — they run on the JVM, so no emulator is
+  needed in CI.
+- Screenshots catch visual drift only. Behavior needs its own tests.
+- Test light and dark, and the largest font scale.
+
+## Accessibility
+
+Structural. Content descriptions on anything meaningful, `null` on anything
+purely decorative — a described decoration is noise to a TalkBack user.
+Minimum touch target 48×48dp. Layout survives the largest font scale.
+TalkBack order must be sensible, not just complete.
+
+## Tooling
+
+Gradle Kotlin DSL — everything is text and reviewable. Verification runs
+through `./gradlew`, not npm; `.orchestra/config.yml` reflects that.
+
+## Toolchain
+
+Gradle (`brew install gradle`), the Android SDK, and `ANDROID_HOME` set.
+The scaffold assembles and tests as generated — `./verify.sh` runs compile,
+test, and lint. Verified against a real build.
+
+Note: AGP 9 has built-in Kotlin support. Do **not** add the
+`org.jetbrains.kotlin.android` plugin — it fails the build.

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

@@ -0,0 +1,12 @@
+Scaffold a new design system component.
+
+Usage: `/web:component {Name}`
+
+1. Load the `design-component` skill and follow it exactly.
+2. Confirm every value the component needs has a token. If one is missing,
+   add it to `src/design/tokens.css` first — do not hardcode.
+3. Create `src/design/{Name}/` with the component, types, tests, fixture,
+   and `index.ts`.
+4. Export it from `src/design/index.ts`.
+5. Run `npm run typecheck && npm test && npm run lint`.
+6. Report the a11y checklist with each item explicitly checked or flagged.

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

@@ -0,0 +1,92 @@
+---
+name: design-component
+description: "Author a component in the design system — folder layout, API shape, tests, fixture, a11y. Use when adding or changing anything under src/design/."
+---
+
+# Authoring a design system component
+
+## Folder
+
+```
+src/design/{Name}/
+├── {Name}.tsx          # the component, nothing else
+├── {Name}.test.tsx     # interaction tests + one snapshot
+├── types.ts            # props and any type this component owns
+└── index.ts            # public exports
+```
+
+Then add the component to `src/design/index.ts`.
+
+## Before writing
+
+1. Does a token exist for every value you are about to use? If not, add the
+   token first. Never hardcode a color, radius, spacing, or duration.
+2. Are you using the right primitive? `Pressable` over `TouchableOpacity`,
+   `FlatList` over a mapped array. A `View` with an onPress is a defect.
+3. Does this component need to know anything about the product? If yes, it
+   does not belong in `src/design/`.
+
+## API
+
+- `forwardRef` to the root element
+- merge `className` in, do not overwrite the caller's
+- spread remaining props onto the root
+- variants and sizes are unions (`"primary" | "danger"`), never independent
+  booleans that can contradict each other
+- no default that hides a required decision
+
+## Tests
+
+Interaction first, snapshot second.
+
+React Native Testing Library 14 — verified working shape. `render` is
+**async** and queries come from `screen`, not from render's return value:
+
+```tsx
+import { render, screen, userEvent } from "@testing-library/react-native";
+import { Button } from "./Button";
+
+test("fires onPress when pressed", async () => {
+  const user = userEvent.setup();
+  const onPress = jest.fn();
+  await render(<Button onPress={onPress} />);
+
+  await user.press(screen.getByRole("button"));
+
+  expect(onPress).toHaveBeenCalledTimes(1);
+});
+
+test("does not fire when disabled", async () => {
+  const user = userEvent.setup();
+  const onPress = jest.fn();
+  await render(<Button onPress={onPress} disabled />);
+
+  await user.press(screen.getByRole("button"));
+
+  expect(onPress).not.toHaveBeenCalled();
+});
+```
+
+`const { getByRole } = render(...)` does not work in v14 — render returns a
+promise, and destructuring it silently yields undefined queries.
+
+Also cover: accessibilityState for disabled/selected, and one snapshot per
+component for markup drift.
+
+If the component wraps a third-party library, test *our* wrapper. A
+Dependabot bump that changes the library's behavior has to turn this suite
+red — that is the entire reason the suite exists.
+
+## Accessibility checklist
+
+- [ ] `accessibilityRole` set correctly
+- [ ] `accessibilityLabel` present and meaningful
+- [ ] `accessibilityState` reflects disabled/selected/checked
+- [ ] touch target at least 44x44pt
+- [ ] layout survives the largest system font scale
+- [ ] contrast holds in both themes
+
+## Done means
+
+Component, types, tests, barrel export, and the a11y checklist — all of
+it. Verified on both iOS and Android; one platform is half an answer.