squad-skills 0.1.0

package/skills/squad-frontend/references/frontend-security-accessibility-and-performance.md

@@ -0,0 +1,55 @@
+# Frontend security, accessibility, and performance
+
+Use for every user-facing change; increase depth for auth, rich text, uploads, third-party scripts,
+payments, multi-tenant data, complex widgets and performance-sensitive routes.
+
+## Browser security and privacy
+
+- Prevent XSS by preserving framework escaping, sanitizing allowed rich HTML with a maintained policy, and
+  avoiding unsafe DOM sinks/dynamic script execution.
+- Treat URL, storage, postMessage, clipboard, deep-link and server payloads as untrusted.
+- Use CSRF protection appropriate to cookie/session design; SameSite alone may not cover every topology.
+- Never put secrets or privileged credentials in client code, public env variables, source maps or logs.
+- Validate postMessage origin/source; constrain iframes; review CSP, Trusted Types and third-party scripts
+  according to threat model.
+- Avoid storing long-lived tokens in script-readable storage when safer session architecture exists.
+- Prevent tenant/object data leakage in cache keys, prefetch, SSR payloads, analytics and error reports.
+- Dependency/registry code is source code: inspect install scripts, generated components and bundle impact.
+
+## Accessibility
+
+Use semantic HTML and native controls before ARIA. Follow WCAG 2.2 and WAI-ARIA Authoring Practices for
+custom widgets. Verify keyboard order, visible focus, names/roles/states, announcements, error association,
+touch targets, contrast, zoom/reflow, text scaling, reduced motion and forced/high contrast where relevant.
+
+Manage focus after dialogs, route transitions, deletion, validation and asynchronous content. Avoid
+positive tabindex and hover-only behavior. Test with accessibility tree plus at least one realistic
+keyboard/screen-reader path for critical flows; automated checks are incomplete.
+
+## Internationalization and content
+
+Support long/short translations, pluralization, locale formatting, RTL, Unicode and timezone/calendar
+semantics. Do not concatenate translatable fragments. Layout must survive realistic content, zoom and
+dynamic font sizes.
+
+## Performance model
+
+Measure route/user journey using field data when available and lab profiles otherwise. Optimize the actual
+bottleneck:
+
+- rendering: avoid unnecessary reactive work, unstable identity and expensive synchronous computation;
+- network: reduce request waterfalls, payloads, duplicate fetches and third-party cost;
+- bundle: route/component split heavy optional code; inspect source maps/analyzer; avoid duplicate libs;
+- images/fonts: correct dimensions/formats, responsive sources, preload only critical assets and control
+  font shifts;
+- hydration/server rendering: minimize client boundary and serialized data; avoid hydration mismatch;
+- lists/charts/editors: virtualize or progressively render only when measured and accessible;
+- memory: clean subscriptions, observers, timers, object URLs, workers and animation contexts.
+
+Protect Core Web Vitals/interaction latency and layout stability, but use project budgets/SLOs rather than
+universal magic thresholds. Animation must not block input or create persistent compositing/memory cost.
+
+## Evidence
+
+Report browser/device/network, build mode, route, measurement tool, baseline/change and limitations.
+Separate static bundle reasoning, local lab, automated browser, installed app and deployed field evidence.

package/skills/squad-frontend/references/frontend-stack-and-motion-selection.md

@@ -0,0 +1,99 @@
+# Frontend stack and motion selection
+
+Read this reference when classifying an existing versus greenfield project, proposing a UI dependency,
+porting a design across frameworks, or implementing non-trivial animation.
+
+## 1. Existing codebase
+
+Preserve the repository's framework, components, tokens, CSS strategy, motion utilities, API/state
+patterns, accessibility semantics, and interaction language. Reuse or extend local primitives. Do not add
+the preferred greenfield stack merely to standardize the project.
+
+A new UI or motion dependency requires a concrete gap, compatibility/performance assessment, and user
+approval.
+
+## 2. Greenfield React/Next.js
+
+- Establish semantic tokens and reusable variants before feature composition.
+- Prefer shadcn/ui for open-code components.
+- Use selected beUI source/patterns when their interaction directly supports the design.
+- Use Motion for React for component-state, enter/exit, layout, gesture, and ordinary scroll-linked motion.
+- Use GSAP only for complex timelines, precise multi-target choreography, ScrollTrigger, or specialized
+  SVG/canvas animation.
+
+## 3. Greenfield Vue/Nuxt
+
+- Establish the same semantic token and variant foundation.
+- Prefer Reka UI for accessible headless primitives.
+- Use the selected CSS/Tailwind token layer for styling.
+- Use shadcn-vue when a shadcn-like styled open-code layer powered by Reka UI is desired.
+- Use Motion for Vue (`motion-v`) for component-state, enter/exit, layout, gesture, and ordinary
+  scroll-linked motion.
+- Use GSAP only for complex timelines, ScrollTrigger, precise choreography, or specialized SVG/canvas.
+
+## 4. Other established web stacks
+
+Preserve these when present; do not rewrite them into React/Vue:
+
+- **Svelte/SvelteKit:** use runes/store conventions matching the project, load/actions/hooks, SSR/client
+  boundaries, progressive enhancement and Svelte transitions where appropriate.
+- **Angular:** preserve standalone/module choice, signals/RxJS boundaries, dependency injection, router,
+  forms and Angular CDK/Material or local design system.
+- **TanStack Start/Router/Query:** respect type-safe routes, loaders/server functions, cache ownership,
+  SSR/dehydration and framework adapter differences.
+- **Solid/SolidStart:** preserve fine-grained reactivity, resources, control-flow primitives and server/client
+  boundaries; do not apply React memoization rules mechanically.
+- **Astro:** keep islands and client directives minimal; prefer server/static HTML and framework components
+  only where interactivity requires them.
+- **Qwik, Lit/Web Components, Preact, Ember or other stacks:** follow repository conventions and official
+  versioned docs; apply the same state, security, accessibility, performance and test contracts.
+
+Framework choice follows rendering/deployment/product needs and team capability—not trend ranking.
+
+## 5. Rendering model
+
+Identify CSR, SPA, SSR, SSG, ISR, streaming, resumability/islands, React Server Components or hybrid
+behavior before choosing data boundaries. Keep secrets/server-only modules outside client graphs. Define
+cache/freshness, hydration, auth, SEO/metadata and failure behavior for each route.
+
+Do not force SSR for authenticated app surfaces without measurable value; do not force SPA-only rendering
+when crawlability, first response, sharing metadata or edge delivery require server/static output.
+
+## 6. Animation implementation
+
+Choose the lightest suitable tool:
+
+- **CSS:** local hover, color, opacity, and small transform transitions.
+- **Motion:** declarative component-state, layout, gesture, enter/exit, and ordinary scroll behavior.
+- **GSAP:** timeline, pin/scrub/snap, multi-target choreography, or advanced SVG/canvas requirements.
+
+Do not let Motion and GSAP control the same elements. Scope selectors to the component. Create animation
+inside the framework lifecycle; revert/kill timelines, contexts, listeners, and ScrollTriggers on teardown.
+Honor responsive variants and reduced motion. Verify that animation does not block input, cause layout
+shift, retain detached DOM, or violate the performance budget.
+
+Use CSS instead of adding Motion or GSAP for an effect CSS already handles cleanly.
+
+### Cross-role ownership
+
+Motion ownership follows authorship: whoever writes the animation code owns its lifecycle scoping,
+teardown, and reduced-motion fallback. Motion arriving inside designer-authored presentational components
+is already scoped and cleaned up there — verify it, do not re-own it. Frontend owns the motion it writes
+while wiring behavior, such as route transitions and data-driven animation, plus dependency approval and
+bundle/performance verification of the whole app.
+
+The shared greenfield baseline is intentionally repeated for standalone operation; keep it aligned with
+Designer's `platform-web-foundations-and-motion.md`, and resolve conflicts through accepted design first,
+then the repository's existing system.
+
+## 7. Cross-framework port
+
+Port the UX contract, component state, keyboard/focus behavior, layout continuity, timing, reduced motion,
+and tokens through the target framework's native composition model. Never paste React components into Vue
+or Vue components into React.
+
+## 8. Selection output
+
+Record the framework and rendering model chosen or preserved, each UI or motion dependency added with
+the gap it closes, the alternatives rejected, and the constraint that decided each. A decision another
+role implements records what would reopen it, not only what was chosen.

package/skills/squad-frontend/references/frontend-testing-debugging-and-mindset.md

@@ -0,0 +1,51 @@
+# Frontend testing, debugging, and mindset
+
+Use for validation strategy, UI failures, rendering/hydration bugs, performance diagnosis and maintainable
+frontend decisions.
+
+## Testing by boundary
+
+- pure unit/property tests for domain utilities, formatters and state transitions;
+- component tests for semantics, interaction, keyboard, forms and state rendering;
+- integration tests for router/query/store/API adapter boundaries with realistic fixtures;
+- contract tests against published Backend schemas/error shapes;
+- browser E2E for critical user journeys, auth/permissions and cross-route behavior;
+- accessibility, visual regression and performance checks where regression risk exists;
+- cross-browser/device matrix derived from supported audience, not every engine mechanically.
+
+Prefer user-visible queries and deterministic events over implementation selectors/sleeps. Mock at network
+or external boundaries; do not mock the component behavior under test. Test error, stale, offline,
+permission and race paths, not only happy loading/success.
+
+## Debugging method
+
+1. Reproduce in the real route, build mode, viewport, browser and account/permission path.
+2. Capture console, network timing/payload shape, DOM/accessibility tree, state/query devtools and traces.
+3. Determine whether source is render, state ownership, stale async result, router, CSS/layout, hydration,
+   browser API, service worker/cache, animation lifecycle or Backend contract.
+4. Reduce to the earliest incorrect state/DOM/network event; form and test a falsifiable hypothesis.
+5. Fix cause, add regression evidence and recheck neighboring states/responsive/a11y/performance.
+
+Hydration debugging compares server markup/data/environment with first client render; do not hide mismatch
+with client-only rendering unless the feature truly requires it. Memory issues require listener/timer/
+observer/subscription/object URL/GSAP/Motion cleanup inspection.
+
+## Code quality
+
+Prefer repository-native patterns, clear ownership and small composable components. Extract hooks/
+composables/services for cohesive behavior, not to satisfy arbitrary line counts. Keep effect dependencies
+honest, avoid derived-state duplication and premature memoization, and preserve framework-specific
+reactivity rules.
+
+## Frontend mindset
+
+- Model user intent and recovery, not screenshots alone.
+- Treat loading/error/permission/offline and long content as product states.
+- Keep URL, server cache and client state ownership explicit.
+- Respect web platform semantics before replacing them with JavaScript.
+- Progressive enhancement and resilience matter where product context supports them.
+- Measure performance and accessibility; do not infer them from clean code.
+- Visual quality, logic, security and operability form one feature—not separate polish phases.
+
+Completion requires fresh type/lint/build/test plus browser evidence proportional to risk and a precise
+statement of what was not tested.

package/skills/squad-frontend/references/frontend-worked-decisions.md

@@ -0,0 +1,71 @@
+# Frontend worked decisions
+
+Read when a motion, cascade, accessibility or scope decision is ambiguous. Adapt the reasoning to the
+repository in front of you; these are not templates.
+
+Each example carries its provenance. **Observed** happened in a run this catalog's maintainers recorded;
+**constructed** is derived from documentation and was not measured. Weigh them accordingly.
+
+## 1. Smooth scroll and scroll-driven animation drift apart
+
+**Context:** A page ships a smooth-scroll library and a scroll-driven timeline. Nothing errors, the page
+scrolls, and pinned sections desync from the eased curve under load.
+
+**Decision:** Give both one clock. Forward the smooth-scroll position into the timeline library's update
+and drive the library from the timeline's ticker, never from a private `requestAnimationFrame` loop. Check
+this integration first when reviewing a scroll-driven page.
+
+**Observed:** the catalog's recorded design runs — the most consequential defect across eight builds of
+one brief, and the one finding a blind judge caught in both reading orders.
+
+## 2. A reduced-motion path is a layout, not a property
+
+**Context:** A horizontal track is revealed by a transform inside a tall pinned section. The obvious
+fallback sets `transform: none` under `prefers-reduced-motion`.
+
+**Decision:** Design the still layout. Re-lay-out those sections as ordinary static scrollers, subscribe to
+mid-session preference changes, and load the page with the preference on to confirm every panel is
+reachable. Removing motion is not the requirement; reaching the content is.
+
+**Observed:** the recorded reduced-motion check asks whether motion was removed and passes on that question
+alone; nothing asks the follow-up. **Constructed:** no run measured a build failing this way — a track laid
+out as `width: max-content` with no `overflow-x` is unreachable under the preference by construction.
+
+## 3. The CSS that wins is not the CSS in the markup
+
+**Context:** A utility class sits in the markup and does nothing; separately, scroll-driven animation stops
+firing after a layout fix.
+
+**Decision:** Put component rules in a cascade layer: an unlayered rule outranks every layered utility. Use
+`overflow-x: clip` rather than `hidden`, which forces the other axis to `auto` and makes `body` its own
+scroll container. Confirm both in the browser, not in the source.
+
+**Observed:** the same runs, verified by reading the computed overflow and `scrollY` before and after.
+
+## 4. A horizontally scrolling region needs a tab stop
+
+**Decision:** An `overflow-x: auto` track with no focusable child gets `tabIndex={0}` and an accessible
+name. Making each card focusable instead also clears the finding, and costs a tab stop per card — prefer it
+only when the cards are interactive anyway. Treat the track as a default review item rather than something
+a brief must request.
+
+**Observed:** the same runs — reported by axe on the mobile viewport of three of four builds.
+
+## 5. Render it and read the numbers
+
+**Decision:** Contrast, hit area and layout overflow are measurements. Build, serve and check the running
+page before handing over; a build that reads its own numbers beats one that was told the rules. The cost is
+real — a measure-fix-remeasure loop took two thirds of one build's time — so spend it on the checks that
+have a number, and leave taste to review.
+
+**Observed:** the same runs, as their widest-reaching finding. Those builds also differed in sandbox
+access, so it is evidence for verifying rather than a measured effect of any instruction.
+
+## 6. One screen's state does not need a store
+
+**Context:** A single screen needs cross-component state and the repository has no global store.
+
+**Decision:** Use the framework's own composition and the existing server-state client. Introduce a store
+when a second consumer or a cross-route requirement exists, not to avoid passing a value.
+
+**Constructed:** the scope rule this role already applies; no recorded run behind it.

package/skills/squad-frontend/references/official-sources.md

@@ -0,0 +1,52 @@
+# Frontend official sources
+
+Use primary documentation for the repository's exact versions. Do not upgrade because a newer guide exists.
+
+## Frameworks and rendering
+
+- Web platform/MDN: https://developer.mozilla.org/docs/Web
+- React: https://react.dev/
+- Next.js: https://nextjs.org/docs
+- React Router: https://reactrouter.com/
+- Vue: https://vuejs.org/guide/
+- Nuxt: https://nuxt.com/docs
+- Svelte/SvelteKit: https://svelte.dev/docs
+- Angular: https://angular.dev/
+- TanStack: https://tanstack.com/, React Query https://tanstack.com/query/latest/docs/framework/react/overview,
+  and Vue Query https://tanstack.com/query/latest/docs/framework/vue/overview
+- Solid: https://docs.solidjs.com/
+- Astro: https://docs.astro.build/
+- Qwik: https://qwik.dev/docs/
+- Lit: https://lit.dev/docs/
+
+## UI, forms, motion, and styling
+
+- shadcn/ui: https://ui.shadcn.com/docs
+- Reka UI: https://reka-ui.com/docs/overview/introduction
+- shadcn-vue: https://www.shadcn-vue.com/docs/introduction
+- beUI (preferred optional source; verify live source/dependencies): https://beui.dev/docs/ai-agents and
+  https://beui.dev/components/motion
+- Motion: https://motion.dev/docs
+- GSAP: https://gsap.com/docs/v3/
+- Tailwind CSS: https://tailwindcss.com/docs
+- React Hook Form: https://react-hook-form.com/get-started
+- Zod: https://zod.dev/
+
+## Security, accessibility, and performance
+
+- HTML/CSS/HTTP standards: https://html.spec.whatwg.org/ , https://www.w3.org/TR/css/ , https://httpwg.org/specs/
+- WCAG 2.2: https://www.w3.org/TR/WCAG22/
+- WAI-ARIA APG: https://www.w3.org/WAI/ARIA/apg/
+- OWASP Cheat Sheets: https://cheatsheetseries.owasp.org/
+- web.dev performance: https://web.dev/performance/
+- Core Web Vitals: https://web.dev/articles/vitals
+
+## Testing
+
+- Vitest: https://vitest.dev/guide/
+- Playwright: https://playwright.dev/docs/intro
+- Testing Library: https://testing-library.com/docs/
+- axe-core: https://github.com/dequelabs/axe-core
+
+When behavior is framework-adapter-specific, read that adapter's docs rather than transferring React rules
+to Vue/Svelte/Angular or vice versa.

package/skills/squad-frontend/references/quality-bar-and-preflight.md

@@ -0,0 +1,49 @@
+# Quality bar and pre-flight
+
+Read before handing a slice to QA, Code Review or the next role. Every check runs in the repository's own
+browser, test and build tooling, so the pass holds with no other skill installed.
+
+## What weak frontend output looks like
+
+- A screen that renders one state. Loading, empty, error, stale, offline, permission-denied and long-content
+  paths exist in the product but not in the component.
+- Tests bound to the implementation: internal selectors, a mocked child that is the behavior under test, a
+  fixed sleep standing in for a deterministic event.
+- A hydration mismatch hidden behind client-only rendering instead of reconciled with the server data.
+- Effects that never clean up — listeners, timers, observers, subscriptions, object URLs, animation
+  instances — so a second mount leaks or double-fires.
+- Derived state duplicated into a store, dishonest effect dependencies, memoization added before any
+  measurement asked for it.
+- Motion with no lifecycle: nothing cancels on unmount, interruption is undefined, and the reduced-motion
+  path removes the transform that was the only thing bringing content into view.
+- Accessibility and performance asserted from clean code. A scrollable track with no tab stop and a 3.4:1
+  label both read fine in review and fail a measurement.
+- A server defect absorbed by the client: a longer timeout, a shape-tolerant parser, a retry that hides the
+  contract break instead of routing it to Backend.
+
+## Pre-flight
+
+Pass every applicable check honestly.
+
+### Behavior and data
+
+- Every state the API, permissions and navigation can produce is reachable and rendered.
+- Fetch, mutate, cache, cancel and retry behavior follows the published contract, not one observed response.
+- URL, server cache and client state each have one owner, and the flow agrees with the logic it renders.
+
+### Platform and accessibility
+
+- Semantic HTML first; keyboard path, focus order and visible focus work across the changed surface.
+- Contrast, labels, announcements and hit areas are measured on the built page, not inferred from tokens.
+- Responsive layout and reduced motion are both exercised, and all content stays reachable under each.
+
+### Code and tests
+
+- Repository patterns preserved; components composed from existing primitives rather than duplicated.
+- Tests query what a user sees, await real events, and cover at least one failure path.
+
+## Proof to hand over
+
+Name the checks that ran — type, lint, build, tests, browser, accessibility, performance — the route,
+viewport and build mode they ran in, and what was not tested. A check that could not run is reported as
+not run, never as a pass.

package/skills/squad-frontend/references/runtime-capability-fallbacks.md

@@ -0,0 +1,49 @@
+# Runtime capability pairing and fallbacks
+
+Read this reference before selecting tools for a phase, and whenever specialist skills, named squad
+gates, Figma MCP, browser inspection, or test infrastructure is in question.
+
+## Specialist skill pairing
+
+Detect specialist skills once per task by inspecting the live skill catalog for the capabilities
+below.
+
+- **Installed** — read this skill's task-relevant references first, then pair the phase-matched
+  specialist skill with this role's contract so it accelerates the phase. This role's boundary, gates,
+  and evidence rules stay authoritative wherever the two disagree.
+- **Absent** — run the native fallback for the same phase at the same standard.
+
+Never auto-install a specialist skill, and never report a skill as run when it does not exist.
+
+## Rules
+
+- Inspect live capabilities before invoking anything.
+- Never invoke a missing command, claim an unavailable gate ran, or weaken verification silently.
+- Never auto-install a skill, MCP server, plugin, or package.
+- Follow project instructions when present. Otherwise infer commands and conventions from README,
+  manifests, framework config, nearby code, and tests.
+- Report only gaps that limit evidence or the requested outcome.
+
+## Capability mapping
+
+| Phase | Pair when installed | Native fallback |
+|---|---|---|
+| Frame/plan | Brainstorm/plan skills | State acceptance criteria and make a proportional plan |
+| Scout | Repository search skill | Search routing, components, API clients, configs, and tests directly |
+| Figma | Figma specialist skills | Use available Figma MCP or user-provided structured exports |
+| Design | `squad-designer`; `ui-ux-pro-max` as reference data only | Run the bounded inline Designer contract |
+| Build/style | Frontend specialist skills | Implement with repository framework, components, and CSS system |
+| API/state | Frontend data/state skill | Follow repository fetch, cache, form, validation, and state patterns |
+| Docs/contract | Docs specialist, `squad-backend` | Inspect contract and current official docs; report Backend mismatch |
+| Debug | Debug/fix skill | Reproduce from logs/browser/tests, isolate cause, and fix directly |
+| Verify | Test/web/a11y skills | Run repository tests, lint, type, build, browser, and manual a11y checks |
+| Review | `squad-qa`, `squad-code-review` | Run equivalent QA and diff-review checklists directly |
+| Commit | Git skill | Use native Git only when the user requests a commit |
+
+## Evidence gaps
+
+If no tool can access required Figma, an API contract, browser state, or test environment, state the exact
+limit and request the smallest accessible artifact. Do not invent verification.
+
+When named QA/Review gates are unavailable, report the native checks that actually ran and any unverified
+area. Their absence does not remove the quality requirement.

package/skills/squad-mobile/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: squad-mobile
+description: "Operate as the squad's Mobile Engineer — build React Native/Expo, Flutter, SwiftUI, or Kotlin/Compose UI; integrate Backend APIs; implement app logic, offline/sync, navigation, secure storage, and platform-native UX. Preserve the existing app stack, pair with installed specialist skills, and fall back to native capabilities when they are absent."
+user-invocable: true
+when_to_use: "Invoke to build a mobile screen or flow with client logic and API integration, or to run the Mobile role solo. Material UI/UX work requires a Designer contract first."
+category: mobile
+keywords: [mobile, react-native, expo, flutter, swiftui, compose, api-integration, offline, sync, ux-flow]
+argument-hint: "[mobile feature or screen]"
+metadata:
+  author: Harry Nguyen
+  version: "1.9.0"
+---
+
+# Squad — Mobile
+
+Build app UI and client logic, consume Backend contracts, and make navigation and platform UX match real
+data, permissions, lifecycle, connectivity, and device constraints. Pair installed specialist skills;
+work natively when they are absent.
+
+**Principles:** existing app first | design before material UI decisions | consume API, do not build it |
+offline and lifecycle explicit | platform-native UX | secure local data | verify on realistic targets.
+
+## Scope and boundary
+
+Own screens, navigation, client/app state, forms, API integration, local persistence/sync, deep links,
+push handling, secure tokens, biometrics and client-side purchase flows.
+
+Do not implement shared server APIs, DB schemas, server business logic, or web UI. Raise contract gaps to
+Backend. Treat API/deep-link/push payloads as untrusted. Never log secrets, tokens, personal data, or
+sensitive device state.
+
+Track each emulator/simulator, packager, watcher, build daemon, port and temporary device resource started
+by the task. Reuse safe project processes, and stop only task-owned resources when work ends.
+
+## Core gates
+
+1. **Preserve the app** — match its framework, architecture, navigation, state, components, platform
+   conventions, native modules, build configuration, accessibility and test patterns.
+2. **Resolve design first** — accepted Figma/design or Designer-authored components must define material
+   UI/UX work; build the presentational layer inline when the Designer capability is unavailable.
+3. **Model lifecycle and connectivity** — foreground/background, process death, offline, retries, stale
+   cache, conflict resolution, permissions, deep links and interrupted flows are first-class states.
+4. **Keep secrets secure** — use platform secure storage and server-enforced authorization; never treat
+   client checks as security boundaries.
+5. **Verify platform behavior** — report simulator/emulator/device, OS, build mode and checks actually run.
+
+## Conditional references
+
+- For Figma/Designer routing, platform UX states, offline/sync, secure storage, push/deep links, IAP and
+  performance gates, read
+  [references/design-platform-and-lifecycle-gates.md](references/design-platform-and-lifecycle-gates.md).
+- For existing-versus-new-app stack selection, React Native/Expo, Flutter, Swift/iOS, Kotlin/Android,
+  KMP/Compose Multiplatform, .NET MAUI, Capacitor, app architecture, state, navigation, networking and
+  offline data, read
+  [references/mobile-stack-architecture-and-data.md](references/mobile-stack-architecture-and-data.md).
+- For mobile threat model, privacy, performance, test layers, release/store and observability, read
+  [references/mobile-security-performance-testing-and-release.md](references/mobile-security-performance-testing-and-release.md).
+- For crash/ANR/render/network/build diagnosis and mobile engineering mindset, read
+  [references/mobile-debugging-and-mindset.md](references/mobile-debugging-and-mindset.md).
+- When calibrating a lifecycle, offline, permission or evidence decision against concrete cases, read
+  [references/mobile-worked-decisions.md](references/mobile-worked-decisions.md).
+- For current primary documentation, read [references/official-sources.md](references/official-sources.md).
+- Before choosing tools for a phase, and when specialist skills, devices, QA, Review, or
+  browser/docs tools are in question, read
+  [references/runtime-capability-fallbacks.md](references/runtime-capability-fallbacks.md).
+
+## Quality bar
+
+Simulator smoothness is not evidence, and a state the app can enter but the build never entered is not
+implemented. Before handing over, run the self-review in
+[references/quality-bar-and-preflight.md](references/quality-bar-and-preflight.md).
+
+## Workflow
+
+1. **Frame and scout** — capture acceptance; inspect architecture, navigation, state, components, API
+   client, persistence, native config, design source, platform targets, tests and build commands.
+2. **Resolve design and contract** — obtain Figma/Designer mapping and actual Backend contract; enumerate
+   navigation, permissions and online/offline/loading/empty/error/success/interrupted states.
+3. **Implement app logic** — integrate fetch/mutate/cache/retry/cancel, local state, persistence/sync,
+   validation and orchestration through repository patterns; coordinate missing endpoints with Backend.
+4. **Build platform UX** — implement screens, navigation, keyboard/insets, accessibility, gestures,
+   lifecycle, deep links and platform conventions without introducing a parallel UI system.
+5. **Verify** — run focused unit/widget/component/integration/e2e tests, type/lint/build, accessibility and
+   relevant device checks; inspect cold start, memory, frame rate and bundle/app size when affected.
+6. **Hand off** — report environment and evidence; route through QA then Code Review when available, or
+   run equivalent native passes and disclose reduced independence.
+
+## Handoff contract
+
+- From Backend, the API contract: the schema, error shape, auth rules, pagination and idempotency
+  behavior the consumer codes against, not a description of the endpoint. A contract gap returns to
+  Backend rather than being worked around in the app.
+- From Designer, the artifact and boundary stated in
+  [references/design-platform-and-lifecycle-gates.md](references/design-platform-and-lifecycle-gates.md);
+  this role wires behavior into what it receives and returns a visual or interaction gap to Designer.
+- To DevOps, the build command and the artifact it produces, which configuration values are baked
+  into that artifact at build time and which are read at runtime, and what the artifact assumes about
+  routing, signing or release channel.
+- To QA, the diff under test, the acceptance criteria it claims to meet, the commands and environment
+  that exercise it, and the checks already run, named against the simulator, device and OS version used.
+- On a QA `FAIL`, the minimal repro, expected versus actual, and the redacted artifacts.
+- From Code Review, severity-ranked findings carrying file:line, failure condition, impact and
+  remediation, and a verdict of `APPROVE`, `CHANGES_REQUESTED` or `NEEDS_EVIDENCE`.
+- QA and Code Review stay mandatory: with neither skill installed this role runs both as separate
+  logical passes and labels them non-independent.
+- When a named squad peer is absent, carry its stage inline at the same standard where this role's
+  boundary allows, and otherwise report the gap; never report a stage as run when no pass actually ran it.
+
+## Completion checklist
+
+- [ ] Every reference the router pointed at was loaded, or the report says why it was skipped
+- [ ] Existing app stack and platform patterns are preserved, or a new-app stack was selected explicitly
+- [ ] Material UI/UX has accepted design mapping and all applicable states
+- [ ] Backend contract is consumed without adding server ownership
+- [ ] Offline, retry, stale data, conflicts, lifecycle and interrupted navigation are defined
+- [ ] Tokens and sensitive data use appropriate secure storage and redacted logging
+- [ ] Deep links, push, permissions, biometrics and IAP behavior are verified when touched
+- [ ] Accessibility and platform conventions are covered
+- [ ] Test/build/device/performance evidence and unverified targets are explicit
+- [ ] The quality-bar pre-flight ran; failed checks were fixed or reported

package/skills/squad-mobile/references/design-platform-and-lifecycle-gates.md

@@ -0,0 +1,50 @@
+# Design, platform, and lifecycle gates
+
+Read for material mobile UI/UX work or when offline, lifecycle, secure storage, deep links, push,
+biometrics, IAP, accessibility, or performance is affected.
+
+## Design gate
+
+The designer hands over presentational component code, not a written spec: screens and components that
+render in the app's framework, with props and slots left open for you to bind, plus the rationale behind
+them. Wire behavior into that code instead of rebuilding it: state, data fetching, API integration,
+routing, forms submission, and platform lifecycle stay with the build role, so navigation, offline, and
+lifecycle behavior are yours to add without altering the visual language.
+
+Motion ownership follows authorship: whoever writes the animation code owns its lifecycle scoping,
+teardown, and reduced-motion fallback. Verify designer-authored motion against real device behavior;
+re-own it only when you rewrite it.
+
+- Treat accepted Figma as design intent and map it to existing app components and platform conventions.
+- Trigger `squad-designer` for new/redesigned UX, missing responsive/adaptive behavior, interaction,
+  accessibility, states, or cross-screen component language.
+- Skip Designer for logic-only work, narrow bugs, complete accepted designs, and exact local patterns.
+- If Designer is unavailable, inspect the codebase, research task-specific mobile flows when needed, then
+  build the presentational components inline — hierarchy, navigation surface, states, platform adaptation
+  and accessibility — before wiring behavior into them.
+- Report a visual or interaction gap back to the Designer stage; do not redesign inside the feature.
+
+## Platform and lifecycle model
+
+Specify applicable behavior for:
+
+- first launch, foreground/background, process death, restore and session expiry;
+- keyboard, safe areas/insets, orientation, dynamic type/font scale and screen sizes;
+- offline, slow network, retry, cancellation, stale cache, conflict resolution and partial sync;
+- permission denied/restricted/permanently denied and settings recovery;
+- deep links from cold/warm start, invalid/expired links and auth redirects;
+- push foreground/background/tap paths, duplication and stale destination;
+- biometric unavailable/changed/locked-out and secure fallback;
+- purchase pending/cancelled/restored/failed and server-side entitlement validation.
+
+## Security and privacy
+
+Use Keychain/Keystore or the framework's secure-storage abstraction for credentials. Store the minimum
+offline data, define retention/clear-on-logout behavior, redact logs/crash reports, and validate all
+external payloads. Client-side permissions and purchase state never replace server authorization.
+
+## Performance and accessibility
+
+Assess cold/warm start, memory, frame drops, list rendering, image/network use, bundle/app size and battery
+only where the change can affect them. Verify labels, focus order, screen reader behavior, contrast,
+touch targets, text scaling, reduced motion and keyboard/switch access as applicable.

package/skills/squad-mobile/references/mobile-debugging-and-mindset.md

@@ -0,0 +1,40 @@
+# Mobile debugging and mindset
+
+Use for crashes, ANRs/watchdogs, jank, memory, networking, build/signing, lifecycle and platform-only bugs.
+
+## Diagnostic method
+
+1. Capture exact device/simulator, OS, app version/build mode, account/data, connectivity, lifecycle state
+   and steps.
+2. Reproduce the earliest wrong behavior; collect symbolicated crash/ANR, logs, network trace, profiler,
+   navigation/state and recent release/config evidence.
+3. Classify: JS/Dart/native crash, main-thread stall, deadlock, memory pressure, render/layout, state race,
+   process restoration, network/auth, storage migration, native module/plugin, signing or store config.
+4. Form one falsifiable hypothesis; test on the narrowest discriminating target.
+5. Fix cause, add regression test, verify lifecycle/offline/neighbor platforms and release build.
+
+Never log/store credentials or private user content for debugging. Use redacted synthetic fixtures. Do not
+disable platform protections, certificate validation or permission checks merely to make a test pass.
+
+## Common evidence paths
+
+- iOS: Xcode console, Organizer/crash logs, Instruments (Time Profiler/Allocations/Leaks/Energy/Network),
+  MetricKit, view debugger, signing/entitlements and device logs.
+- Android: Logcat, Android Studio profiler, Perfetto, Layout Inspector, Memory Analyzer, ANR traces,
+  StrictMode, Network Inspector, Gradle/build scan and Play vitals.
+- React Native/Expo: native logs first for crashes; React DevTools/profiler, Metro, Expo logs/build details,
+  Hermes/profile and native module lifecycle.
+- Flutter: DevTools timeline/CPU/memory/network/widget inspector, shader/jank evidence and platform logs.
+
+## Mobile mindset
+
+- The OS owns process lifetime, scheduling, background execution and permissions.
+- Network, battery, storage, screen size, input and device capability are variable constraints.
+- Respect platform expectations while preserving product identity.
+- Offline is an explicit product/data decision, not a blanket default.
+- Design for interruption, one-handed use, accessibility and recovery.
+- Measure release builds on representative devices; simulator smoothness is not proof.
+- Cross-platform does not erase platform-specific code, testing, store policy or UX.
+- Choose architecture and abstractions by change pressure and native integration cost, not fashion.
+
+Completion requires fresh build/tests plus target-specific evidence proportional to risk and clear gaps.