coding-os 0.3.2__py3-none-any.whl

templates/fastapi/stack.yaml

@@ -0,0 +1,57 @@
+version: 1
+id: fastapi
+language: python
+label: "FastAPI + Pydantic + PostgreSQL"
+category: backend
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/app/
+    ├── api/v1/          # thin routes
+    ├── services/        # business logic
+    ├── schemas/         # pydantic models
+    └── db/              # models + migrations
+  notes: "routes thin, logic in services; SQLAlchemy under db/"
+primary_skill: python-fastapi
+skills: [python-fastapi]
+
+substitutions:
+  DOMAIN_ROUTES: "Backend→`docs/playbooks/fastapi-service.md`"
+  SKILL_ROUTES: "Backend→`python-fastapi`"
+  ENGINEERING_RULE_ROUTING: "Backend→`docs/engineering/fastapi-rules.md`"
+  TOOL_ROUTING_IMPL: "`lint-backend`, `test-backend`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-backend + test-backend"
+  VERIFY_BACKEND: "`cd src/backend && ruff check . && pytest -q`"
+  QUICK_ROUTING: |-
+    - Backend / API task → [FastAPI Service Playbook](./playbooks/fastapi-service.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-FASTAPI` → `./playbooks/fastapi-service.md`
+    - `REF:FASTAPI-RULES` → `./engineering/fastapi-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-FASTAPI", path: "./playbooks/fastapi-service.md", desc: "FastAPI service playbook"}
+  - {code: "REF:FASTAPI-RULES",    path: "./engineering/fastapi-rules.md",  desc: "FastAPI engineering rules"}
+
+routing_entries:
+  - "Backend / API task → [FastAPI Service Playbook](./docs/playbooks/fastapi-service.md)"
+
+rules:
+  - {file: rules/backend.md, globs: ["src/backend/**/*.py"]}
+
+makefile_targets:
+  - {name: lint-backend, cmd: "cd src/backend && ruff check ."}
+  - {name: test-backend, cmd: "cd src/backend && pytest -q"}
+
+verify:
+  - {glob: "src/backend/**/*.py", suites: "lint-backend + test-backend", cmd: "cd src/backend && ruff check . && pytest -q"}
+
+dimensions:
+  - {name: "API endpoint",   read_files: ["docs/playbooks/fastapi-service.md", "docs/engineering/fastapi-rules.md"]}
+  - {name: "Pydantic model", read_files: ["docs/engineering/fastapi-rules.md"]}
+
+skill_enforcement:
+  - {globs: ["src/backend/**/*.py"], primary: python-fastapi, secondary: [clean-code, api-design, backend-fundamentals, hexagonal-architecture, auth-patterns, security-web, testing-strategy, observability]}
+  - {globs: ["src/backend/**/models.py", "src/backend/**/db/**/*.py", "src/backend/**/migrations/**/*.py"], primary: python-fastapi, secondary: [clean-code, db-design, backend-fundamentals]}
+  - {globs: ["src/backend/**/auth*.py", "src/backend/**/security.py"], primary: python-fastapi, secondary: [auth-patterns, security-web, clean-code]}

templates/flutter/rules/mobile.md

@@ -0,0 +1,26 @@
+<!-- domain:FLUTTER | layer:policy | ssot:true | updated:2026-06-14 -->
+# Flutter — stack rules
+
+> P: Compact rule list applied to every `src/mobile/**/*.dart` file in addition to clean-code, frontend-fundamentals, and a11y.
+> R: Reviewing or writing any Flutter code.
+> S: Touching the web frontend or backend.
+> N: [skills/flutter/SKILL.md](../skills/flutter/SKILL.md), [skills/flutter/references/anatomy.md](../skills/flutter/references/anatomy.md)
+
+## Hard rules
+
+1. **Three-state UI.** Every data-fetching screen renders loading / error / empty / content explicitly — `AsyncValue.when` is the canonical switch.
+2. **Widgets stay dumb.** A widget renders state and emits intents; business logic lives in a provider / notifier, never in `build()`.
+3. **One error mapper.** Only `lib/core/error_mapper.dart` turns a thrown failure into UI state; widgets never `try/catch` to build a message.
+4. **No `setState` for shared state.** Cross-screen state goes through a Riverpod provider; `setState` is for ephemeral, single-widget UI only.
+5. **a11y on every interactive element.** Wrap actionable widgets in `Semantics` (label + button/header role); icon-only buttons require a `tooltip`.
+6. **No hard-coded design tokens.** Read colours / spacing / text styles from `Theme.of(context)`, never literal hex / magic numbers.
+7. **`const` constructors by default.** A widget that can be `const` must be — it is the cheapest rebuild win.
+8. **Boundary.** May import from `src/shared/`. Never from `src/frontend/`, `src/backend/`, `src/ai-service/`.
+
+## Pre-commit checklist
+
+- [ ] Three-state branches present on every async screen.
+- [ ] No business logic inside `build()`.
+- [ ] `Semantics` / `tooltip` on every interactive widget.
+- [ ] Tokens read from `Theme.of(context)`, no literal colours.
+- [ ] `dart analyze` clean (no warnings) and `flutter test` green.

templates/flutter/scaffold/docs/engineering/flutter-rules.md

@@ -0,0 +1,35 @@
+<!-- domain:MOBILE | layer:rules | ssot:true | updated:{{DATE}} -->
+# Flutter Engineering Rules
+
+Purpose: Non-negotiable conventions for the {{PROJECT_NAME}} Flutter app.
+Read when: Editing anything under `src/mobile/`.
+Skip when: Frontend/backend work.
+Read next: [Flutter App Playbook](../playbooks/flutter-app.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Hard rules
+
+1. **Layering** — widget → provider → service, imports flow one way only (the
+   table in the `flutter` skill is the SSOT). A widget never imports a service.
+2. **Dumb widgets** — a widget renders state and emits intents; any logic in a
+   `build()` method is a review finding. Business logic lives in a notifier.
+3. **One error shaper** — only `lib/core/error_mapper.dart` turns a thrown
+   failure into UI state; it logs full detail and surfaces a safe message — no
+   stack traces, no driver strings to the user.
+4. **Three-state fail-closed** — every async screen renders loading / error /
+   empty / data explicitly via `AsyncValue.when`; a missing branch ships a frame
+   of blank or jank.
+5. **State discipline** — shared state goes through a Riverpod provider injected
+   by `ProviderScope`; `setState` is reserved for ephemeral single-widget UI.
+6. **Strict analysis** — `dart analyze` with `flutter_lints` is the gate; an
+   ignore comment requires a written justification at the site.
+7. **No floating config** — environment access happens once at bootstrap;
+   providers receive typed config, never read `Platform.environment` directly.
+
+## Testing bar
+
+Providers / notifiers ≥ unit-tested per public method with a `ProviderContainer`;
+screens ≥ loading + error + data path via `pumpWidget` with overridden providers;
+services integration-tested against a fake transport. Never bind a real network
+call in a widget test.

templates/flutter/scaffold/docs/playbooks/flutter-app.md

@@ -0,0 +1,45 @@
+<!-- domain:MOBILE | layer:playbook | ssot:true | updated:{{DATE}} -->
+# Flutter App Playbook
+
+Purpose: The end-to-end recipe for adding or changing a screen, widget, or provider in {{PROJECT_NAME}}.
+Read when: Any task that adds a screen, reusable widget, Riverpod provider, route, or service.
+Skip when: Pure infra/devops work — see the deployment docs.
+Read next: [Flutter Engineering Rules](../engineering/flutter-rules.md), [Error Format](../api-contracts/error-format.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Add a screen (the only sanctioned path)
+
+1. **State first** — model the screen's data as an immutable value and expose it
+   from a provider in `lib/state/<feature>_provider.dart`. Async data uses
+   `AsyncValue` so loading / error / data fall out of the type.
+2. **Service** — `lib/services/<feature>_service.dart` owns transport (HTTP /
+   storage / platform channel). It returns domain values or throws a typed
+   failure; it never touches widgets.
+3. **Screen** — `lib/screens/<feature>_screen.dart`: a `ConsumerWidget` that
+   `watch`es the provider and renders `value.when(loading, error, data)`. No
+   business logic in `build()`.
+4. **Widgets** — extract reusable presentational pieces into `lib/widgets/`;
+   they take data in and emit callbacks, holding no provider reads of their own
+   beyond what they render.
+5. **Route** — register the screen in the single declarative router
+   (`lib/core/router.dart`); never push raw `MaterialPageRoute` from a widget.
+6. **Error mapping** — failures surface through `lib/core/error_mapper.dart`,
+   which converts a thrown failure into the `AsyncError` the screen renders.
+7. **Test** — widget-test the screen's three states via `pumpWidget` with a
+   `ProviderScope` override; unit-test the provider/notifier in isolation.
+8. **Verify** — `cd src/mobile && dart analyze && flutter test`.
+
+## Global wiring (set once in `main.dart`)
+
+`runApp` mounts a single `ProviderScope` over a `MaterialApp.router` bound to the
+declarative router. Theme + error mapper are wired here so every screen inherits
+one token set and one failure shape.
+
+## Anti-patterns
+
+- Business logic inside `build()` — it belongs in a provider / notifier.
+- A widget calling a service directly — go through a provider so it stays testable.
+- `try/catch` building an error message in a screen — the error mapper owns it.
+- `Navigator.push(MaterialPageRoute(...))` from deep in a widget — route through
+  the declarative router instead.

templates/flutter/scaffold/src/mobile/lib/core/error_mapper.dart

@@ -0,0 +1,17 @@
+import 'dart:developer' as developer;
+
+// The ONLY place that turns a thrown failure into a user-safe message.
+// Screens render the returned string; full detail goes to the log, never
+// the UI (no stack traces, no transport strings to the user).
+String mapError(Object error, StackTrace stackTrace) {
+  developer.log(
+    'unhandled failure',
+    name: '{{PROJECT_NAME}}',
+    error: error,
+    stackTrace: stackTrace,
+  );
+  if (error is FormatException) {
+    return 'We received an unexpected response. Please try again.';
+  }
+  return 'Something went wrong. Please try again.';
+}

templates/flutter/scaffold/src/mobile/lib/core/router.dart

@@ -0,0 +1,13 @@
+import 'package:go_router/go_router.dart';
+
+import '../screens/health_screen.dart';
+
+// The single declarative router — widgets never push raw routes.
+final GoRouter appRouter = GoRouter(
+  routes: <RouteBase>[
+    GoRoute(
+      path: '/',
+      builder: (context, state) => const HealthScreen(),
+    ),
+  ],
+);

templates/flutter/scaffold/src/mobile/lib/main.dart

@@ -0,0 +1,22 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import 'core/router.dart';
+
+// runApp bootstrap only — one ProviderScope, one router, no business logic.
+void main() {
+  runApp(const ProviderScope(child: App()));
+}
+
+class App extends StatelessWidget {
+  const App({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp.router(
+      title: '{{PROJECT_NAME}}',
+      theme: ThemeData(colorSchemeSeed: Colors.indigo, useMaterial3: true),
+      routerConfig: appRouter,
+    );
+  }
+}

templates/flutter/scaffold/src/mobile/lib/screens/health_screen.dart

@@ -0,0 +1,32 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../core/error_mapper.dart';
+import '../state/health_provider.dart';
+
+// A ConsumerWidget that renders the three states of an async value.
+class HealthScreen extends ConsumerWidget {
+  const HealthScreen({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final status = ref.watch(healthStatusProvider);
+    return Scaffold(
+      appBar: AppBar(title: const Text('{{PROJECT_NAME}}')),
+      body: Center(
+        child: status.when(
+          loading: () => const CircularProgressIndicator(),
+          error: (error, stackTrace) => Semantics(
+            label: 'Health check failed',
+            child: Text(mapError(error, stackTrace)),
+          ),
+          data: (value) => Semantics(
+            header: true,
+            label: 'Health status $value',
+            child: Text('status: $value'),
+          ),
+        ),
+      ),
+    );
+  }
+}

templates/flutter/scaffold/src/mobile/lib/services/health_service.dart

@@ -0,0 +1,11 @@
+// Transport lives here — screens never call this directly, only via a provider.
+// Returns a domain value or throws a typed failure for the error mapper.
+class HealthService {
+  const HealthService();
+
+  Future<String> status() async {
+    // Stand-in for a real health check (HTTP / platform channel).
+    await Future<void>.delayed(const Duration(milliseconds: 50));
+    return 'ok';
+  }
+}

templates/flutter/scaffold/src/mobile/lib/state/health_provider.dart

@@ -0,0 +1,13 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../services/health_service.dart';
+
+// Provider owns business logic; the screen only watches the AsyncValue.
+final healthServiceProvider = Provider<HealthService>(
+  (ref) => const HealthService(),
+);
+
+final healthStatusProvider = FutureProvider<String>((ref) async {
+  final service = ref.watch(healthServiceProvider);
+  return service.status();
+});

templates/flutter/scaffold/src/mobile/pubspec.yaml

@@ -0,0 +1,22 @@
+name: {{PROJECT_NAME}}
+description: "{{PROJECT_NAME}} Flutter app."
+publish_to: "none"
+version: 0.1.0
+
+environment:
+  sdk: ">=3.4.0 <4.0.0"
+  flutter: ">=3.22.0"
+
+dependencies:
+  flutter:
+    sdk: flutter
+  flutter_riverpod: ^2.5.1
+  go_router: ^14.2.0
+
+dev_dependencies:
+  flutter_test:
+    sdk: flutter
+  flutter_lints: ^4.0.0
+
+flutter:
+  uses-material-design: true

templates/flutter/scaffold/src/mobile/test/health_provider_test.dart

@@ -0,0 +1,90 @@
+// Sample test for the Flutter scaffold — exercises the EXISTING health feature:
+// the FutureProvider (state/) wired to HealthService (services/), and the error
+// frame routed through the single error mapper (core/). Follows the flutter
+// SKILL Testing section: providers tested via a ProviderContainer with the
+// service overridden by a fake, the screen pumped inside a ProviderScope
+// asserting the loading/error/data frames. No real network is bound.
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+import '../lib/screens/health_screen.dart';
+import '../lib/services/health_service.dart';
+import '../lib/state/health_provider.dart';
+
+// A fake that returns a fixed status — no transport, fully deterministic.
+class _FakeHealthService extends HealthService {
+  const _FakeHealthService(this._status);
+
+  final String _status;
+
+  @override
+  Future<String> status() async => _status;
+}
+
+// A fake that throws, so the screen's error frame is forced through mapError.
+class _ThrowingHealthService extends HealthService {
+  const _ThrowingHealthService();
+
+  @override
+  Future<String> status() async => throw const FormatException('bad payload');
+}
+
+void main() {
+  group('healthStatusProvider', () {
+    test('resolves to the value the injected service returns', () async {
+      final container = ProviderContainer(
+        overrides: [
+          healthServiceProvider.overrideWithValue(
+            const _FakeHealthService('ok'),
+          ),
+        ],
+      );
+      addTearDown(container.dispose);
+
+      final result = await container.read(healthStatusProvider.future);
+
+      expect(result, 'ok');
+    });
+  });
+
+  group('HealthScreen', () {
+    Widget pumpWith(HealthService service) => ProviderScope(
+          overrides: [healthServiceProvider.overrideWithValue(service)],
+          child: const MaterialApp(home: HealthScreen()),
+        );
+
+    testWidgets('shows the loading frame before the status resolves',
+        (tester) async {
+      await tester.pumpWidget(pumpWith(const _FakeHealthService('ok')));
+
+      expect(find.byType(CircularProgressIndicator), findsOneWidget);
+
+      await tester.pumpAndSettle();
+    });
+
+    testWidgets('renders the status once the service resolves',
+        (tester) async {
+      await tester.pumpWidget(pumpWith(const _FakeHealthService('ok')));
+      await tester.pumpAndSettle();
+
+      expect(find.text('status: ok'), findsOneWidget);
+      expect(find.byType(CircularProgressIndicator), findsNothing);
+    });
+
+    testWidgets('maps a thrown failure to a user-safe message, never the detail',
+        (tester) async {
+      await tester.pumpWidget(pumpWith(const _ThrowingHealthService()));
+      await tester.pumpAndSettle();
+
+      // The single error mapper turns FormatException into a safe string and
+      // never leaks the thrown detail — the client-side equivalent of the
+      // error envelope's "message safe to show end-users" rule.
+      expect(
+        find.text('We received an unexpected response. Please try again.'),
+        findsOneWidget,
+      );
+      expect(find.textContaining('bad payload'), findsNothing);
+    });
+  });
+}

templates/flutter/scaffold-boundary.yaml

@@ -0,0 +1,28 @@
+# Scaffold boundary for the flutter stack.
+# Schema: docs/governance/scaffold-boundary-contract.md
+# SSOT for what `src/mobile/` may write, read, or import.
+
+version: 1
+stack: flutter
+
+roots:
+  - src/mobile/
+
+file_patterns:
+  - "src/mobile/**/*.dart"
+  - "src/mobile/**/*.yaml"
+
+imports_from:
+  - src/shared/
+  - src/shared/types/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/backend/
+  - src/ai-service/
+
+notes:
+  - "Widgets render, state holds business logic, services own transport — keep the layers one-directional."
+  - "One error mapper in lib/core is the only place that turns a failure into UI state."
+  - "Cross-stack types live in src/shared — never import directly from another stack root."

templates/flutter/skills/flutter/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: flutter
+tier: stack
+domain: [mobile]
+description: Use when creating or modifying Dart files under src/mobile/ in a Flutter app — screens, widgets, Riverpod providers/notifiers, services, navigation, and their tests. Triggers on any .dart change under src/mobile/. Covers the widget→provider→service layering, the single declarative router, three-state AsyncValue UI, the one error mapper, const-rebuild discipline, Semantics-based a11y, and provider/widget testing. Dart language fundamentals live in clean-code; generic UI in frontend-fundamentals.
+globs: "src/mobile/**/*.dart"
+depends_on:
+  - clean-code
+  - frontend-fundamentals
+  - a11y
+last_reviewed: "2026-06-14"
+---
+
+REQUIRED BACKGROUND: You MUST also follow `clean-code` (naming, structure, error paths), `frontend-fundamentals` (three-state async UI), and `a11y` (screen-reader semantics). This skill adds Flutter-specific patterns on top.
+
+Anatomy reference: [`references/anatomy.md`](references/anatomy.md). Read that file BEFORE writing any new screen / widget / provider.
+
+# flutter
+
+## Layer contract (matches `structure.tree`)
+
+| Layer | May import | Never |
+|---|---|---|
+| `screens/` (ConsumerWidget) | the feature provider, widgets | services, other screens |
+| `state/` (provider / notifier) | services, other providers | Flutter `widgets`/`material`, `BuildContext` |
+| `services/` | HTTP client, storage, platform channels | providers, widgets |
+| `widgets/` | the data + callbacks passed in | services, providers it does not render |
+| `core/` (error mapper, router, theme) | providers (for routing guards) | services |
+
+State stays widget-free — a notifier never imports `BuildContext` — so it is
+unit-testable and a transport swap (REST → GraphQL → local DB) is a
+service-layer-only change.
+
+## State & DI
+
+- One feature = one provider file (`health_provider.dart`) exposing the service
+  binding plus the `AsyncValue` the screen watches.
+- `ProviderScope` is mounted once in `main.dart`; tests override it per case.
+- Inject services through a `Provider`; never `HealthService()` inside `build()`
+  — that bypasses overrides and breaks testing.
+- Prefer `FutureProvider` / `AsyncNotifier` for async data — the `AsyncValue`
+  carries loading/error/data so the screen cannot forget a state.
+
+## Widgets (dumb)
+
+- A screen `watch`es a provider → renders `value.when(loading, error, data)` →
+  emits intents via callbacks. No business logic in `build()`.
+- Extract reusable presentational pieces into `widgets/`; they take data in and
+  call back out, owning no transport.
+- `const` constructor wherever the widget allows — it is the cheapest rebuild win.
+
+## Navigation
+
+- ONE declarative router in `core/router.dart` (`go_router`). Widgets navigate by
+  name/path through the router; never `Navigator.push(MaterialPageRoute(...))`
+  from deep in the tree.
+
+## Error handling
+
+- ONE error mapper (`core/error_mapper.dart`) turns a thrown failure into the
+  message a screen shows; it logs full detail and returns a safe string —
+  unknown errors get a generic message, never a stack trace or transport string.
+
+## Accessibility
+
+- Wrap interactive widgets in `Semantics` (label + button/header role);
+  icon-only buttons carry a `tooltip`. Read tokens from `Theme.of(context)`,
+  never literal colours / spacing.
+
+## Testing
+
+- Providers/notifiers: unit tests via a `ProviderContainer`, override the service
+  with a fake — no widgets.
+- Screens/widgets: `pumpWidget` inside a `ProviderScope` with overridden
+  providers, asserting the loading + error + data frames minimum.
+- Never bind a real network call in a widget test; inject a fake service.

templates/flutter/skills/flutter/references/anatomy.md

@@ -0,0 +1,64 @@
+<!-- domain:FLUTTER | layer:reference | ssot:true | updated:2026-06-27 -->
+# Flutter Anatomy
+
+> P: Canonical file map + entity recipes for the Flutter (Riverpod, declarative-router) stack.
+> R: Adding any `.dart` under `src/mobile/`, or routing a mobile task.
+> S: Reading backend / web code — wrong stack.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: `src/templates/flutter/scaffold-boundary.yaml`.
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| Screen | `lib/screens/<feature>_screen.dart` | `<feature>_screen.dart` | state, widgets | One widget tree per route (`ConsumerWidget`) |
+| Widget | `lib/widgets/<name>.dart` | `<name>.dart` | — | Reusable presentational component |
+| State | `lib/state/<feature>_provider.dart` | `<feature>_provider.dart` | services | Riverpod provider / notifier — business logic |
+| Service | `lib/services/<name>_service.dart` | `<name>_service.dart` | `http` | Transport + platform access |
+| Core | `lib/core/` | `<name>.dart` | none | Error mapper, router, theme |
+| Test | `test/<file>_test.dart` | `<file>_test.dart` | source under test | `flutter_test` |
+
+## 3. Entity recipes
+
+### Add a new screen
+- **Trigger:** "add a `<feature>` screen / route".
+- **Files emitted:**
+  1. `lib/screens/<feature>_screen.dart`
+  2. `lib/state/<feature>_provider.dart`
+  3. `test/<feature>_screen_test.dart`
+- **Steps:**
+  1. `ConsumerWidget`; watch the provider, render from its state.
+  2. Send user intent to the notifier; never hold business logic in the widget.
+  3. Register the route in the declarative router (`lib/core/`).
+
+### Add a new component
+- **Trigger:** "extract a reusable widget".
+- **Files emitted:** `lib/widgets/<name>.dart` (+ test).
+- **Steps:**
+  1. Stateless + parameterized; no provider reads — pass data in.
+
+### Add a new test
+- **Trigger:** any new screen / widget / provider.
+- **Files emitted:** `test/<file>_test.dart`.
+- **Steps:**
+  1. `ProviderContainer` for state; `testWidgets` + `pumpWidget` for UI.
+
+## 4. Conventions
+
+#### Naming
+- Files: `snake_case.dart`. Classes: `PascalCase`; members: `camelCase`.
+
+#### Test colocation
+- Mirrored: `test/<file>_test.dart` mirrors `lib/<file>.dart`.
+
+#### Dependency rules
+- ✓ screen → state → service.
+- ✗ a widget never turns a failure into UI text — the one core error mapper does.
+- ✗ `src/mobile/` never imports from `src/frontend/` / `src/backend/` — share via `src/shared/`.

templates/flutter/stack.yaml

@@ -0,0 +1,70 @@
+version: 1
+id: flutter
+language: dart
+label: "Flutter + Dart"
+category: mobile
+
+structure:
+  root: src/mobile
+  tree: |
+    src/mobile/
+    ├── pubspec.yaml
+    └── lib/
+        ├── main.dart           # runApp bootstrap (no logic)
+        ├── screens/            # one widget tree per route (StatelessWidget/ConsumerWidget)
+        ├── widgets/            # reusable presentational components
+        ├── state/              # providers / notifiers (Riverpod by default)
+        ├── services/           # transport + platform access (HTTP, storage, native channels)
+        └── core/               # cross-cutting: error mapper, router, theme
+  notes: "widgets render, state holds business logic, services own transport; one error mapper is the ONLY place that turns a failure into UI state; navigation via a single declarative router"
+primary_skill: flutter
+skills: [flutter]
+
+# VERIFY_MOBILE_* override the "(none)" mobile defaults from base.yaml; the
+# aggregator joins substitution keys across stacks via _derive_substitutions.
+substitutions:
+  DOMAIN_ROUTES: "Mobile→`docs/playbooks/flutter-app.md`"
+  SKILL_ROUTES: "Mobile→`flutter`"
+  ENGINEERING_RULE_ROUTING: "Mobile→`docs/engineering/flutter-rules.md`, Error format→`docs/api-contracts/error-format.md`"
+  TOOL_ROUTING_IMPL: "`lint-mobile`, `test-mobile`, `build-mobile`"
+  VERIFY_MOBILE_GLOB: "`src/mobile/`"
+  VERIFY_MOBILE_SUITES: "lint-mobile + test-mobile"
+  VERIFY_MOBILE: "`cd src/mobile && dart analyze && flutter test`"
+  QUICK_ROUTING: |-
+    - Flutter screen / widget task → [Flutter App Playbook](./playbooks/flutter-app.md)
+    - State / provider work → [Flutter App Playbook](./playbooks/flutter-app.md)
+    - Navigation / routing change → [Flutter App Playbook](./playbooks/flutter-app.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-FLUTTER` → `./playbooks/flutter-app.md`
+    - `REF:FLUTTER-RULES` → `./engineering/flutter-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-FLUTTER", path: "./playbooks/flutter-app.md",     desc: "Flutter app playbook"}
+  - {code: "REF:FLUTTER-RULES",    path: "./engineering/flutter-rules.md", desc: "Flutter engineering rules"}
+
+routing_entries:
+  - "Flutter screen / widget task → [Flutter App Playbook](./playbooks/flutter-app.md)"
+  - "State / provider work → [Flutter App Playbook](./playbooks/flutter-app.md)"
+
+rules:
+  - {file: rules/mobile.md, globs: ["src/mobile/**/*.dart"]}
+
+makefile_targets:
+  - {name: lint-mobile,  cmd: "cd src/mobile && dart analyze"}
+  - {name: test-mobile,  cmd: "cd src/mobile && flutter test"}
+  - {name: build-mobile, cmd: "cd src/mobile && flutter build apk --debug"}
+
+verify:
+  - {glob: "src/mobile/**/*.dart", suites: "lint-mobile + test-mobile", cmd: "cd src/mobile && dart analyze && flutter test"}
+
+dimensions:
+  - {name: "Flutter screen",     read_files: ["docs/playbooks/flutter-app.md", "docs/engineering/flutter-rules.md"]}
+  - {name: "Flutter component",  read_files: ["docs/engineering/flutter-rules.md"]}
+  - {name: "State / provider",   read_files: ["docs/engineering/flutter-rules.md", "docs/playbooks/flutter-app.md"]}
+  - {name: "Navigation / route", read_files: ["docs/playbooks/flutter-app.md"]}
+  - {name: "Accessibility",      read_files: ["docs/engineering/flutter-rules.md"]}
+
+skill_enforcement:
+  - {globs: ["src/mobile/**/*.dart"], primary: flutter, secondary: [clean-code, frontend-fundamentals, mobile-fundamentals, a11y]}
+  - {globs: ["src/mobile/**/screens/**/*.dart", "src/mobile/**/widgets/**/*.dart"], primary: flutter, secondary: [clean-code, state-management, performance]}
+  - {globs: ["src/mobile/**/state/**/*.dart"], primary: flutter, secondary: [state-management, clean-code]}

templates/go/rules/backend.md

@@ -0,0 +1,19 @@
+---
+globs: ["src/backend/**/*.go"]
+alwaysApply: false
+---
+
+# Go Backend Rules (auto-loaded on src/backend/**/*.go)
+
+When editing any Go file under `src/backend/`, follow these standards:
+
+- **Return errors, don't panic.** Panic is for programming errors, not runtime conditions.
+- **Wrap errors with `%w`** — `fmt.Errorf("create user: %w", err)`. Compare with `errors.Is` / `errors.As`.
+- **Context first** — every cross-boundary function takes `ctx context.Context` as the first argument.
+- **No context in struct fields.** Propagate, don't store.
+- **Goroutine ownership is explicit** — document who starts and who stops each goroutine.
+- **Table-driven tests** with subtests via `t.Run`. `-race` in CI.
+
+Canonical policy: `docs/engineering/go-rules.md`
+Playbook: `docs/playbooks/go-service.md`
+Primary skill: `go-patterns`