groundwork-method 0.0.1 → 0.10.0

package/src/engineer-skills/groundwork-flutter-engineer/references/testing.md

@@ -0,0 +1,135 @@
+# Testing
+
+## Table of Contents
+- [The Taxonomy](#the-taxonomy)
+- [The Prove-Once Rule](#the-prove-once-rule)
+- [Unit Tests](#unit-tests)
+- [Widget Tests](#widget-tests)
+- [Integration Tests](#integration-tests)
+- [Patrol — the OS Boundary Only](#patrol--the-os-boundary-only)
+- [Golden Tests](#golden-tests)
+- [CI Lanes](#ci-lanes)
+- [Test Commands](#test-commands)
+
+---
+
+## The Taxonomy
+
+| Tier | Scope | Runs on | Budget |
+|---|---|---|---|
+| Unit | view models, repositories, mappers (pure Dart) | anywhere, milliseconds | generous |
+| Widget | feature views via `testWidgets` | headless, seconds | **the bulk of coverage** |
+| `integration_test` | happy-path E2E through the real binary | headless Android emulator | thin — minutes per test |
+| Patrol | flows crossing the Flutter/OS boundary | emulator/device | only when the OS is in the flow |
+| Goldens (alchemist) | design-system-level components | CI with text-as-blocks variants | component library only |
+
+Pick the **cheapest tier that can carry the assertion**. If a widget test can prove it, an integration test that proves it is waste.
+
+## The Prove-Once Rule
+
+Capability behaviour is proven once, headless, at the core's contract. The surface suite proves three things only:
+
+1. **Wiring** — the typed client/repository is called with the right inputs.
+2. **Rendering** — core state renders correctly (including error and empty states).
+3. **Interaction** — commands fire, navigation moves, errors surface.
+
+A widget or integration test re-asserting a business rule (price calculation, permission logic, validation semantics) is a review finding: it duplicates a proof that exists at the contract and couples this suite to core internals.
+
+## Unit Tests
+
+Pure Dart, **fakes over mocks**. An in-memory fake implementing the abstract repository survives refactors that stub-and-verify mocks break on, and doubles as the widget-test fixture:
+
+```dart
+class FakeOrderRepository implements OrderRepository {
+  FakeOrderRepository({List<Order> seed = const []}) : _orders = [...seed];
+  final List<Order> _orders;
+  Order? lastPlaced;
+
+  @override
+  Future<List<Order>> recent({bool refresh = false}) async => _orders;
+
+  @override
+  Future<Order> place(PlaceOrderRequest req) async {
+    final order = Order(id: 'fake-${_orders.length}', /* ... */);
+    _orders.add(order);
+    lastPlaced = order;
+    return order;
+  }
+}
+```
+
+View models are tested through `ProviderContainer` with overrides — no widget tree (see `references/state-management.md` for the pattern). Test the real Notifier; never mock the unit under test.
+
+## Widget Tests
+
+The bulk of coverage. Pump the View inside a `ProviderScope` with fake repositories; assert through **semantics and visible text**, not widget types or internal keys:
+
+```dart
+testWidgets('placing an order shows the confirmation', (tester) async {
+  final fakeRepo = FakeOrderRepository(seed: [draftOrder]);
+  await tester.pumpWidget(ProviderScope(
+    overrides: [orderRepositoryProvider.overrideWithValue(fakeRepo)],
+    child: MaterialApp(theme: buildLightTheme(), home: const OrderView()),
+  ));
+  await tester.pumpAndSettle();
+
+  await tester.tap(find.bySemanticsLabel('Place order'));
+  await tester.pumpAndSettle();
+
+  expect(find.text('Order placed'), findsOneWidget);
+  expect(fakeRepo.lastPlaced, isNotNull);
+});
+```
+
+Conventions:
+
+- Finder priority: `find.bySemanticsLabel` → `find.text` → `find.byTooltip` → `find.byIcon` → (`find.byType`/keys only as a last resort). Semantics-based finds break on user-visible regressions only — and they keep the UI accessible, because inaccessible UI is untestable UI.
+- Pump with the real theme (`buildLightTheme()`) so theme extensions resolve; pump both themes for theme-sensitive components.
+- Cover error and empty states, not just the happy path — rendering core failure states is half the surface's job.
+- `pumpAndSettle` is for settling real transitions, not a sleep. If a test needs settling tricks, the awaited state is not modelled — assert on it explicitly.
+
+## Integration Tests
+
+`integration_test/` drives the real app binary. Keep it to **happy paths, one flow per critical journey**, with the gateway faked or staged:
+
+```dart
+void main() {
+  IntegrationTestWidgetsFlutterBinding.ensureInitialized();
+
+  testWidgets('the app boots to the home view', (tester) async {
+    await tester.pumpWidget(ProviderScope(
+      overrides: [statusRepositoryProvider.overrideWithValue(FakeStatusRepository())],
+      child: const App(),
+    ));
+    await tester.pumpAndSettle();
+    expect(find.text('Wired to the workspace gateway'), findsOneWidget);
+  });
+}
+```
+
+Every integration test costs emulator minutes — the most expensive test currency in this stack. If a widget test can carry the assertion, move it down a tier.
+
+## Patrol — the OS Boundary Only
+
+Add Patrol (LeanCode) only when a flow **leaves Flutter for the OS**: permission dialogs, push notifications, system sign-in sheets, WebViews, home/recents behaviour. It also brings full test isolation and sharding. A Patrol suite duplicating pure-Flutter flows `integration_test` already covers is scope creep — the boundary is the OS, not preference for its `$` finder DSL.
+
+## Golden Tests
+
+Goldens guard **design-system-level components** (the token-projected theme made visible), via **alchemist** with its platform-test vs CI-test split (CI variants render text as blocks, killing font flakiness). Scope is the component library, not full screens — screen-level goldens churn on every copy change and teach rubber-stamping. `golden_toolkit` is discontinued: migrate, never adopt.
+
+## CI Lanes
+
+- **PR gate:** `flutter analyze` + `flutter test` (unit + widget, headless, fast).
+- **Boot lane:** `flutter test integration_test` on a headless Android emulator — `reactivecircus/android-emulator-runner@v2`, x86_64, `-no-window -gpu swiftshader_indirect -no-snapshot-load -no-snapshot-save`, KVM-enabled runner.
+- **iOS is a local-only / device-farm lane (Firebase Test Lab, Codemagic), never a CI gate** — it needs macOS runners and hands, and putting it in the gate breaks the headless loop.
+- A runner without the Flutter SDK reports the tier **skipped-with-reason, never silently green**.
+
+## Test Commands
+
+| Command | Purpose |
+|---|---|
+| `npx nx run <app>:test` | unit + widget tests (guarded: skips-with-reason without the SDK) |
+| `npx nx run <app>:analyze` | static analysis |
+| `npx nx run <app>:test-integration` | integration_test against a device/emulator |
+| `flutter test test/home_view_test.dart` | single file |
+| `flutter test --name 'refresh'` | by test name |

package/src/engineer-skills/groundwork-flutter-engineer/references/theming-and-design-tokens.md

@@ -0,0 +1,109 @@
+# Theming and Design Tokens
+
+## Table of Contents
+- [The Projection Model](#the-projection-model)
+- [The Generated Palette Module](#the-generated-palette-module)
+- [Consuming the Theme](#consuming-the-theme)
+- [Theme Extensions for Semantic Roles](#theme-extensions-for-semantic-roles)
+- [Dark Mode](#dark-mode)
+- [Typography](#typography)
+- [Evolving the Brand](#evolving-the-brand)
+- [Material/Cupertino Freeze Note](#materialcupertino-freeze-note)
+
+---
+
+## The Projection Model
+
+The theme is **generated from the design system's brand tokens**, not authored in the app. The chain:
+
+```
+docs/design-system.md  →  .groundwork/config/brand-tokens.json (visual block)
+                       →  lib/ui/core/theme/brand_palette.dart   (GENERATED)
+                       →  lib/ui/core/theme/app_theme.dart       (builds ThemeData)
+                       →  Theme.of(context) in widgets
+```
+
+The same tokens drive every surface of the product (web, CLI, mobile), so cross-surface visual consistency is a build artifact, not a review hope. The consequence for implementation work: **a hex literal in a widget file is a review finding** — it forks the design system silently.
+
+## The Generated Palette Module
+
+`brand_palette.dart` carries the projected token values and is regenerated, never hand-edited:
+
+- Palette roles in both themes: `primaryLight/primaryDark`, `accent…`, `surface…`, `surfaceAlt…`, `textBody…`, `success…`, `error…`, `warning…`, `info…`.
+- Typography families and weights: `displayFontFamily`, `bodyFontFamily`.
+- Shape: `radiusBase`.
+
+Widgets do **not** import `brand_palette.dart`. Only `app_theme.dart` reads it, building `ThemeData` (ColorScheme, TextTheme, component themes, ThemeExtensions) from the constants. The palette is the projection artifact; the theme is the API.
+
+## Consuming the Theme
+
+```dart
+@override
+Widget build(BuildContext context) {
+  final theme = Theme.of(context);
+  return Container(
+    decoration: BoxDecoration(
+      color: theme.colorScheme.surfaceContainerHighest,
+      borderRadius: BorderRadius.circular(BrandPalette.radiusBase), // only via shared components
+    ),
+    child: Text('Title', style: theme.textTheme.titleLarge),
+  );
+}
+```
+
+Resolution order when you need a colour or style:
+
+1. A `ColorScheme` role (`primary`, `surface`, `error`, `onSurface`, ...).
+2. A `ThemeExtension` (semantic roles the scheme lacks — see below).
+3. A shared component (e.g. a `Card` whose shape the component theme already sets).
+4. If none fits, the design system is missing a decision — raise it; do not inline a value.
+
+Never: `Color(0xFF...)`, `TextStyle(fontSize: 13)`, `EdgeInsets.all(13)` with non-scale values, opacity-hacked variants of brand colours.
+
+## Theme Extensions for Semantic Roles
+
+Material's `ColorScheme` has no success/warning/info roles. The theme defines them as a `ThemeExtension` built from the palette:
+
+```dart
+final status = Theme.of(context).extension<StatusColors>()!;
+Icon(Icons.check_circle, color: status.success);
+```
+
+When a new semantic role is needed (e.g. a "highlight" colour), extend the `ThemeExtension` in `app_theme.dart` from a palette/token value — do not scatter one-off colours.
+
+## Dark Mode
+
+Both themes are built from the same palette (each role carries light and dark values — a design-system commitment, not an option):
+
+```dart
+MaterialApp.router(
+  theme: buildLightTheme(),
+  darkTheme: buildDarkTheme(),
+  themeMode: ThemeMode.system,
+)
+```
+
+Implementation rules:
+
+- Never branch on `Theme.of(context).brightness` to pick hardcoded colours — the scheme and extensions already resolved per-theme values.
+- Every visual change is verified in both themes (widget tests pump both when the component is theme-sensitive — see `references/testing.md`).
+
+## Typography
+
+`app_theme.dart` applies the projected families to the `TextTheme` (display family on headlines/titles, body family elsewhere). Widgets use `textTheme` slots — `headlineMedium`, `titleLarge`, `bodyMedium` — never raw `TextStyle`s with families or sizes.
+
+The families only render once their font assets are bundled in `pubspec.yaml` (`fonts:` section). Until then Flutter falls back silently — if the type looks wrong, check the asset bundling before the theme code.
+
+## Evolving the Brand
+
+When the design system changes:
+
+1. The design-system run updates `brand-tokens.json`.
+2. Regenerate (or mechanically update) `brand_palette.dart` to match — the file header marks it as generated.
+3. `app_theme.dart` and all widgets pick the change up for free.
+
+If a visual change cannot be expressed through tokens → palette → theme, that is a design-system gap to raise, not a license to hand-edit the palette.
+
+## Material/Cupertino Freeze Note
+
+Material and Cupertino are frozen in the core framework as of Flutter 3.44 and are moving to standalone `material_ui`/`cupertino_ui` packages with independent versioning. When those packages land in this app's pubspec, pin them deliberately and review the theme builder against their migration notes — expect the dependency shift; do not be surprised by it.

package/src/engineer-skills/groundwork-flutter-engineer/references/widgets-and-composition.md

@@ -0,0 +1,123 @@
+# Widgets and Composition
+
+## Table of Contents
+- [Composition Over Inheritance](#composition-over-inheritance)
+- [Extract Widgets, Not Helper Methods](#extract-widgets-not-helper-methods)
+- [const Discipline](#const-discipline)
+- [Build Purity](#build-purity)
+- [Keys](#keys)
+- [Layout Decisions](#layout-decisions)
+- [Review Checklist](#review-checklist)
+
+---
+
+## Composition Over Inheritance
+
+New UI composes existing widgets; it never subclasses a widget to alter behaviour. A `PrimaryButton` wraps and configures `FilledButton`; it does not extend it:
+
+```dart
+class PrimaryButton extends StatelessWidget {
+  const PrimaryButton({super.key, required this.label, this.onPressed});
+
+  final String label;
+  final VoidCallback? onPressed;
+
+  @override
+  Widget build(BuildContext context) {
+    return FilledButton(
+      onPressed: onPressed,
+      child: Text(label),
+    );
+  }
+}
+```
+
+Flutter's rendering model rewards exactly one style — small, pure, const-friendly widgets composed deeply. Every deviation is something the next change must special-case.
+
+---
+
+## Extract Widgets, Not Helper Methods
+
+`Widget _buildHeader()` defeats const canonicalisation and rebuild isolation — the framework cannot skip a subtree it cannot identify. Extract a widget class instead:
+
+```dart
+// WRONG — helper method
+Widget _buildHeader(BuildContext context) => Row(children: [...]);
+
+// RIGHT — extracted widget, rebuild-isolated, const-capable
+class _Header extends StatelessWidget {
+  const _Header({required this.title});
+  final String title;
+  @override
+  Widget build(BuildContext context) => Row(children: [...]);
+}
+```
+
+Extract when a subtree is reused, when it can become `const`, or when a build method stops fitting on a screen.
+
+---
+
+## const Discipline
+
+Every constructor that can be `const` is `const`; every instantiation site that can use `const` does. A `const` widget is canonicalised and skipped during rebuilds — the cheapest performance work in the framework. `flutter_lints` (`prefer_const_constructors` and friends) enforces this; treat those lints as errors, not suggestions.
+
+Practical habit: when a `const` keyword fails to compile, ask why the widget isn't const-capable before deleting the keyword — often a value should be passed in rather than computed inline.
+
+---
+
+## Build Purity
+
+`build` reads state and returns widgets. It never:
+
+- mutates state (including provider state),
+- fires network requests,
+- shows dialogs or snackbars,
+- starts animations or timers.
+
+Flutter may call `build` at any frequency; an impure build turns rebuild cadence into behaviour. Side effects belong in view-model commands, lifecycle hooks (`initState`, `ref.listen`), or explicit handlers:
+
+```dart
+// Side-effect on state change: ref.listen, not build.
+ref.listen(submitOrder, (prev, next) {
+  if (next is MutationError) {
+    ScaffoldMessenger.of(context).showSnackBar(/* ... */);
+  }
+});
+```
+
+A conditional in `build` that encodes a business rule belongs in the view model; `build` branches on view state only.
+
+---
+
+## Keys
+
+Keys appear in exactly three situations:
+
+1. **Reorderable/filterable lists** — `ValueKey(item.id)` on each child, so state follows identity, not position.
+2. **Tree-shape changes around stateful widgets** — preserving state when conditionals restructure the tree.
+3. **`GlobalKey` for the rare imperative handle** — forms (`FormState`), nothing else.
+
+A key sprinkled "to be safe" is noise. A missing key on a reorderable list is a state-corruption bug. A `GlobalKey` reaching into another widget's state is a view model that wasn't written.
+
+---
+
+## Layout Decisions
+
+- **`LayoutBuilder` over `MediaQuery.of(context).size`** — a widget responds to its parent's constraints, not the screen. MediaQuery-based layout breaks the moment the widget is placed in a pane, sheet, or test harness.
+- Spacing and sizes come from the theme/density system, not magic numbers (see `references/theming-and-design-tokens.md`).
+- Tap targets meet the 48dp minimum (see `references/accessibility.md`).
+
+---
+
+## Review Checklist
+
+Flag in review:
+
+- [ ] Any subclassed framework widget (composition exists).
+- [ ] `Widget _buildX()` helper methods returning subtrees.
+- [ ] Missing `const` where the lint reports it.
+- [ ] Side effects (mutation, requests, dialogs, animation starts) inside `build`.
+- [ ] Business-rule conditionals inside `build`.
+- [ ] `Color(0xFF...)`, raw `TextStyle(...)`, or magic paddings (theme violation — see theming reference).
+- [ ] Lists built from dynamic collections without `ValueKey`s.
+- [ ] `MediaQuery.size` used for layout branching.

package/src/engineer-skills/groundwork-flutter-engineer/sync-anchor.md

@@ -0,0 +1,15 @@
+# Sync Anchor
+
+This file pins the principle files this skill embeds. When any listed file
+changes, this skill must be reviewed in the same commit. CI verifies the
+hashes match.
+
+| Principle file | SHA-256 | Last reviewed |
+|---|---|---|
+| src/generators/flutter-app/docs/principles/stack/flutter/index.md | 45c86182ebbaf4be599f54a22a7e8bbebbc455bbdcacda4fbec845f2de041885 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/architecture.md | ac10c2c87da358157973ebbfe07657491d68a248b946b00697fdc5e18f3af596 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/state-management.md | a690a3476453cb8ed0af0d3f48566d8ba6a2d508ac1ef782fd27bbffd2268994 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/widgets-and-composition.md | b45c55220f14a7886837c4d4159b33febceed772db32a7efb277e7dba00512e8 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/testing.md | 5aec7d7c5300cf6f4c4f4b07809ff02010505cf71329f7dc5b766de39b97685e | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/platform-channels.md | 6b5a54dcb8b55433b7175cf715a6a3abf03c86c317f2037af6155a131691cfb2 | 2026-06-12 |
+| src/generators/flutter-app/docs/principles/stack/flutter/releases-and-distribution.md | 70ecdca2be6d8476359dbc2e72e3510157b49db0f5512cded76e0e3f19bed46f | 2026-06-12 |

package/src/engineer-skills/groundwork-go-engineer/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: groundwork-go-engineer
+description: >
+  Implement and review Go service changes using self-contained engineering
+  references and the current repository as the source of truth. Use for Go
+  backend handlers, services, providers, domain models, migrations, telemetry,
+  structured logging, dependency injection, tests, concurrency, or service
+  architecture. This skill is the execution router for Go backend work: it loads
+  reference docs selectively, preserves core/edge boundaries and the inward
+  dependency rule, coordinates with adjacent skills, and verifies changes
+  against contracts and tests. Use this
+  skill whenever the user works in a Go service directory or asks about Go
+  backend behavior, even if they do not explicitly ask for a "go engineer."
+---
+
+# Go Engineer
+
+Go backend execution router for service repositories. Durable engineering guidance lives in `references/`; this skill decides what to load, how to route the task, what repository facts to verify, and which safety gates apply.
+
+## Operating Contract
+
+1. Load reference docs from `references/` for architectural and implementation guidance. Treat the current repository's code, specs, and generated contracts as the source of truth for naming, structure, and behavior.
+2. Inspect the current repository before naming packages, commands, import paths, schemas, or generated files.
+3. Load the smallest reference set that explains the task. Add more context only when the task crosses a boundary.
+4. Preserve the service's dependency direction and public contracts. Code implements OpenAPI, database migrations, event schemas, and documented architecture — it does not invent them.
+5. Coordinate with adjacent skills when another skill owns the primary decision surface.
+
+---
+
+## Code intelligence (repo map + Serena)
+
+GroundWork gives you a deterministic **repo map** (`npx groundwork-method repo-map` — tree-sitter import edges + PageRank centrality, cached to `.groundwork/cache/repo-map.json`) and the **Serena** MCP server (LSP-backed symbol navigation and editing), registered at init. Orient before reading widely: refresh the map, read its `centrality` ranking to find the hubs, then use Serena to navigate them (`get_symbols_overview` / `find_symbol` / `find_referencing_symbols`) and make reference-aware edits (`replace_symbol_body` / `rename`). Full workflow and the graceful-degradation contract live in `.groundwork/skills/code-intelligence.md`; fall back to ordinary reads and edits when they are unavailable.
+
+---
+
+## Required First Checks
+
+Before non-trivial Go implementation or review work:
+
+| Check | Why |
+|---|---|
+| Service package layout and nearby examples for the touched layer | Prevents inventing structure that already has a convention |
+| `go.mod` for Go and dependency versions | Avoids version-specific advice that contradicts the project |
+| OpenAPI spec (if HTTP behavior changes) | HTTP contracts are generated — code must match the spec |
+| Database schema file + migration tooling (if schema changes) | Schema is target-state — migrations derive from it |
+| Event specs (AsyncAPI, Protobuf, etc.) for async/real-time behavior | Event types drive code generation downstream |
+
+---
+
+## Context Routing
+
+Load only the rows relevant to the current task. Reference files are in the skill's `references/` directory.
+
+| Task shape | Reference to load |
+|---|---|
+| Any non-trivial service change | `architecture.md`, `implementation-patterns.md`, `go-services.md` |
+| Go idioms, context, interfaces, DI, errors, config validation | `go-services.md` |
+| Concurrency, goroutine lifecycle, errgroup, context cancellation | `concurrency.md` |
+| Layer placement, new boundary, dependency direction | `architecture.md` |
+| Capability interface + provider (LLM etc.), generated adapter shape, bare-interface bet, `add-capability` | `capability-ports.md`, `architecture.md` |
+| HTTP endpoint, handler, idempotency, CORS | `http-handlers.md`, `api-design.md` |
+| Database repository, SQL, declarative schema, test isolation | `postgres.md` |
+| Observability — tracing, structured logging, metrics | `observability.md` |
+| Reliability — retries, timeouts, graceful shutdown, backpressure | `reliability-performance.md` |
+| Performance — latency budgets, load shedding, profiling | `reliability-performance.md` |
+| Events, Pub/Sub, WebSocket, async integration | `integration-realtime-data.md` |
+| Tests, quality gates, coverage strategy, flake triage | `testing.md` |
+| Code quality, naming, simplicity, deletion | `code-craft-security.md` |
+| Security, auth, secrets, input validation, supply chain | `code-craft-security.md` |
+
+---
+
+## Skill Handoffs
+
+Use the smallest collaborating set. Keep the Go engineer as lead when the work is mainly Go implementation inside a service directory.
+
+| Condition | Hand off to |
+|---|---|
+| Endpoint shape, OpenAPI, error envelope, pagination, idempotency, SDK generation, webhooks, versioning | API architect / API design skill |
+| Schema, migrations, indexes, query plans, constraints, RLS, retention, vector/full-text search | Database / Postgres design skill |
+| Streaming, Pub/Sub, WebSockets, event schemas, replay, fan-out, idempotency, source-aware updates | Real-time / event architecture skill |
+| Test strategy, CI quality gates, contract tests, flake reduction, validation design | Test architecture skill |
+| Deployment, Cloud Run, Terraform, Docker, CI/CD, observability infrastructure, local dev tooling | Platform engineering skill |
+
+If the collaborating skill does not exist in the project, handle the concern inline but flag it as outside this skill's primary scope.
+
+---
+
+## Execution Checklist
+
+1. **Identify the touched contract surface** — domain behavior, HTTP contract, database schema, event contract, operational behavior, or tests.
+2. **Load minimal routed references** and inspect nearby code before designing.
+3. **State important inferences** when guidance comes from general Go knowledge rather than project-specific docs or code.
+4. **Implement within existing conventions** — do not create new layer boundaries without evidence from docs or existing code.
+5. **Run targeted tests/checks** when feasible. If not feasible, explain the blocker and name the exact command to run later.
+6. **Summarize** references consulted, files changed, verification performed, and residual risks.
+
+---
+
+## Safety Gates
+
+These constraints prevent the most common classes of architectural damage in Go services.
+
+### Naming and Boundaries
+- Do not invent package paths, command names, contract files, or service boundaries. Verify them in the repository first.
+- Do not create new layer boundaries without evidence from docs or existing code.
+
+### Layer Discipline
+- Do not put business decisions in handlers, edge implementations, middleware, migrations, or generated code when the architecture expects them in domain/service code.
+- Do not leak implementation-specific types across the core/edge boundary. If a database driver type appears in a core interface, the architecture is broken.
+- Always validate configuration at startup (e.g., `envconfig`); do not scatter `os.Getenv` throughout the codebase.
+
+### Inbound Defenses & API Standards
+- Do not use offset/limit pagination for collections; enforce cursor-based pagination.
+- Do not allow mutating endpoints (POST/PATCH) without an `Idempotency-Key` implementation to prevent duplicate side-effects.
+- Do not omit inbound concurrency limits (load shedding); shed load rather than queuing indefinitely.
+- Never use wildcard CORS (`AllowedOrigins: []string{"*"}`).
+
+### Error Handling
+- Do not log and return the same error at multiple layers. Wrap errors with context and log at the boundary established by existing code.
+
+### Concurrency
+- Do not launch untracked goroutines. Verify cancellation, error collection, and shutdown behavior for every concurrent operation.
+
+### Contract & Data Integrity
+- Do not change HTTP behavior without checking the OpenAPI source and any generated-client workflow.
+- Do not change database behavior without checking the target-state schema, the migration workflow, and dry-run output when feasible. Use declarative schemas.
+- Do not add or modify domain event types without updating the corresponding event spec.
+
+### Generation
+- Do not run code generation manually outside documented generation flows.
+
+---
+
+## Quick Reference
+
+Frequently needed patterns. Verify against the actual repository before using them.
+
+### Domain Error Pattern
+
+| Sentinel pattern | HTTP mapping | Use |
+|---|---|---|
+| `ErrNotFound` | 404 | Resource lookup miss |
+| `ErrUnauthorized` | 401 | Missing or invalid auth |
+| `ErrForbidden` | 403 | Valid auth, insufficient permission |
+| `ErrConflict` | 409 | Duplicate resource |
+| `ErrPayloadTooLarge` | 413 | File exceeds size/duration limit |
+| `ErrInvalidFormat` | 415 | Input format validation failure |
+| `ErrValidation` (catch-all) | 422 | Field-level validation failures |
+
+### Mock Pattern
+
+Hand-written mocks with settable `Func` fields. Read the mock file before writing tests — function signatures often include parameters easy to miss from the interface alone.
+
+### Event Broadcast Pattern
+
+Domain mutations broadcast via an event hub in service methods. For testing, use a mock event hub and assert captured events. Async events use a transactional outbox pattern.
+
+### Idempotency Middleware
+
+Caches responses by key + user ID. For tests, implement an in-memory repository rather than depending on the production store.
+
+---
+
+## Output Expectations
+
+- Name the references or source files that informed non-obvious decisions.
+- Separate verified repository facts from recommendations based on general Go knowledge.
+- Provide concrete verification commands and results.
+- For code reviews: findings first, ordered by severity, with file references and missing-test risks.
+- For implementation work: changed files, behavior, tests, and follow-up risks.

package/src/engineer-skills/groundwork-go-engineer/references/api-design.md

@@ -0,0 +1,82 @@
+# API Design
+
+## Core Principles
+
+### 1. Contract-First, Code-Generated
+
+Specs live in `/specs` and are the source of truth. Server handlers, typed clients, and reference docs are generated from them. Write the spec before the handler. Hand-rolled clients drift; generated clients cannot.
+
+### 2. Explicit Versioning, Additive Evolution
+
+Breaking changes require a new major version and a documented deprecation window. Within a major version, evolve additively: new optional fields, new endpoints, new response codes. Existing clients must never break from schema extension.
+
+### 3. Resources, Not RPCs
+
+HTTP endpoints model resources (`POST /entities`, `GET /entities/{id}`), not verbs (`POST /createEntity`). The resource shape forces identity, lifecycle, and composition reasoning up front. When a verb is unavoidable, name it carefully and document why a resource shape does not fit.
+
+### 4. Idempotency by Design
+
+Every write endpoint accepts an `Idempotency-Key` header. The server stores the key long enough to detect replays; the client is not responsible for being careful.
+
+### 5. Pagination and Filtering Are Uniform
+
+Every collection endpoint paginates with the same cursor shape, filters with the same query-string grammar, and returns the same `next`/`prev` link structure. Inconsistent pagination is a design smell.
+
+### 6. Errors Are Structured and Machine-Readable
+
+Every error response carries a stable code, a human message, and a `details` object. Clients branch on the code, not on the prose. Error codes are catalogued and never renumbered.
+
+### 7. AI-Agent Readability Is a First-Class Concern
+
+OpenAPI specs include rich descriptions on every field, enumerations for every finite domain, and explicit examples on every endpoint. An agent reading the spec should be able to use the API correctly without reading the handler.
+
+### 8. Async Events Are Contracts Too
+
+WebSocket and Pub/Sub events receive the same rigour as HTTP — AsyncAPI spec, generated client and server models, additive evolution.
+
+## Error Envelope (RFC 9457)
+
+All error responses follow this shape:
+
+```json
+{
+  "status": 404,
+  "title": "Not Found",
+  "detail": "No entity with the provided id exists.",
+  "instance": "/entities/abc123"
+}
+```
+
+Validation errors include a field-level `errors` array:
+
+```json
+{
+  "status": 422,
+  "title": "Unprocessable Entity",
+  "detail": "Request body did not match the schema.",
+  "errors": [
+    { "message": "required", "path": "body.title", "value": "" }
+  ]
+}
+```
+
+## Common HTTP Status Codes
+
+| Status | Title | Meaning | Action |
+|---|---|---|---|
+| 401 | Unauthorized | Missing or invalid auth token | Re-authenticate |
+| 403 | Forbidden | Authenticated but not authorised | Confirm role. Do not retry |
+| 404 | Not Found | Resource does not exist | Verify identifier |
+| 422 | Unprocessable Entity | Request body did not match schema | Inspect `errors` array |
+| 409 | Conflict | Idempotency-Key reused with different payload | Generate a fresh key |
+| 429 | Too Many Requests | Rate limit exceeded | Back off per `Retry-After` |
+| 504 | Gateway Timeout | Downstream dependency timed out | Retry with backoff |
+| 500 | Internal Server Error | Unexpected server error | Retry with backoff; escalate if sustained |
+
+## Anti-Patterns
+
+- **Breaking changes without a version bump.** The assumption "no one uses that field" is always wrong.
+- **Hand-written clients.** Clients drift. Generate.
+- **Kitchen-sink endpoints.** Split large payloads into focused endpoints.
+- **Error payloads as strings.** Structured errors, always.
+- **Endpoint-scoped pagination conventions.** Pick one and apply universally.