groundwork-method 0.0.1 → 0.10.0

package/src/engineer-skills/groundwork-go-engineer/references/integration-realtime-data.md

@@ -0,0 +1,57 @@
+# Integration Patterns
+
+## Principles
+
+1. **Default to async; upgrade to sync when required.** Sync only for inline response values or strict writes.
+2. **Outbox pattern for DB write + event agreement.** Write event to `outbox` table in same transaction; worker relays to broker.
+3. **Every consumer is idempotent.** De-duplication key or idempotent operations (UPSERT, conditional update).
+4. **Retries have policies.** Explicit maximum, backoff curve, dead-letter destination.
+5. **Webhooks verify, sign, and replay.** HMAC signature over payload. Both sides support replay.
+6. **Timeouts are end-to-end budgets.** Allocated from the outermost caller's budget.
+7. **Circuit breakers protect the system.** Open after threshold, fast-fail, probe periodically.
+8. **Every integration has a contract test.** Real signature verification, retry curve, idempotency in CI.
+
+## Anti-Patterns
+
+- Sync chains three deep. Fire-and-forget webhooks. Commit-and-then-publish.
+- Global retry policies. Dead-letter queues as logs.
+
+---
+
+# Real-Time Architecture
+
+## Principles
+
+1. **WebSocket is the default transport.** SSE for one-way server-to-client only. No long-polling.
+2. **Every message carries a sequence number.** Monotonic, per-session. Detect gaps, duplicates, resync.
+3. **Reconnection is the normal case.** Exponential backoff, jitter, resumption token.
+4. **Backpressure is explicit.** Shed, coalesce, or block. Never buffer unbounded.
+5. **Echo suppression is a design concern.** Specified before the first line of code.
+6. **Idempotent handlers.** Same sequence number processed twice has no additional effect.
+7. **Observability is unbroken across the socket.** OTel trace context propagates into the socket.
+8. **Client state is recoverable, not sacred.** Server is the source of truth.
+
+## Anti-Patterns
+
+- Socket as fire-and-forget bus. Per-connection unbounded buffers. Reconnect-then-refetch-everything.
+- Ad-hoc event schemas. Client-side echo reconciliation.
+
+---
+
+# Data Engineering
+
+## Principles
+
+1. **Events are append-only and immutable.** Correction via compensating events.
+2. **Schemas are versioned and evolvable.** Additive new fields; deprecated fields have a deadline.
+3. **Partition keys are chosen deliberately.** Ordering guarantee per partition.
+4. **CQRS where it pays.** Separate read model for complex projections.
+5. **Event sourcing is a tool, not a religion.** Only where change history is the product.
+6. **Data contracts are documented, versioned, and owned.**
+7. **Retention is a design decision.** Decided at creation, enforced by automation.
+8. **Backfills are planned operations.** Rehearsed in staging, measured in production.
+
+## Anti-Patterns
+
+- Silent schema changes. Mutable event logs. Kitchen-sink events table.
+- Backfills without rehearsal. Retention by accident.

package/src/engineer-skills/groundwork-go-engineer/references/observability.md

@@ -0,0 +1,49 @@
+# Observability
+
+## Core Principles
+
+### 1. OpenTelemetry Is the Common Language
+
+Every service emits traces, metrics, and logs through OpenTelemetry SDKs to a single collector. Vendor lock-in at the collector boundary, not inside application code.
+
+### 2. Traces Are the Primary Signal
+
+Given a choice between adding a metric or enriching a trace, enrich the trace. Traces preserve causality; metrics aggregate it away.
+
+### 3. The Three Pillars Are One Pillar
+
+Logs, metrics, and traces are different projections of the same events. A log line includes its trace ID; a metric includes dimensions to pivot back to traces; an exemplar on a metric points directly at the trace that produced it.
+
+### 4. Dashboards Derive from SLOs
+
+Every dashboard starts with the user-journey SLO it supports. Then latency percentiles, error rates, saturation, and traffic. Dashboards derived from SLOs stay useful; dashboards assembled by adding "interesting-looking" graphs drift.
+
+### 5. Trace-Driven Development
+
+Sketch the trace a new feature should produce *before* writing the handler. What spans must exist? What attributes? What parent-child relationships? The instrumentation design shapes the code.
+
+### 6. Assert on Telemetry in Tests
+
+System tests assert that traces are unbroken end-to-end — a missing span is a test failure. Instrumentation is part of the contract, not an optional decoration.
+
+### 7. Logs Are Structured, Sampled, and Contextual
+
+Every log line is structured (JSON), carries its trace ID, and is emitted at an agreed severity. Sample aggressively at debug and info; do not sample errors.
+
+### 8. Cardinality Is a Design Choice
+
+High-cardinality attributes (per-user, per-tenant) are valuable for debugging but expensive in storage. Tag deliberately — high cardinality on traces, lower cardinality on metrics.
+
+## Implementation
+
+- Use `slog` exclusively for structured logging. Always inject `trace_id` and `span_id` from the current context.
+- Every HTTP endpoint and background job must initialize a Root Span.
+- Adapter calls (SQL queries, Pub/Sub publishing) must extract and cascade the span.
+
+## Anti-Patterns
+
+- **Pillar-at-a-time adoption.** "We'll add metrics now, traces later." You will not.
+- **Vendor SDKs in application code.** Application code imports OpenTelemetry; the collector talks to the vendor.
+- **Dashboards without SLOs.** Pretty charts without a question they answer.
+- **Logs-as-debugger.** Using `printf` style logging to trace a single bug. Write a test; add a span.
+- **Cardinality explosions.** Putting a UUID in a Prometheus label.

package/src/engineer-skills/groundwork-go-engineer/references/postgres.md

@@ -0,0 +1,41 @@
+# Postgres
+
+## Principles
+
+1. **Schema design is a design document.** What it represents, identifies, invariants, queries, retention.
+2. **Columns over JSONB for stable shape.** JSONB for varying shape or rarely queried metadata.
+3. **Migrations are additive, reversible, online.** Nullable columns or cheap defaults. Never block on large rewrites.
+4. **Indexes are evidence-based.** Justified by `pg_stat_user_indexes` and `pg_stat_statements`.
+5. **`pgvector` is the vector store.** Operational simplicity over marginal dedicated-DB performance.
+6. **Connection management is explicit.** Deliberate pool sizing, idle timeouts, statement timeouts.
+7. **Query patterns are reviewed.** `EXPLAIN ANALYZE` in PRs for non-trivial queries.
+8. **Backups and retention are not afterthoughts.** Test restores. Retention decided at table creation.
+
+## Target-State Schema Workflow
+
+1. `db/schema.sql` describes the desired final state.
+2. Migrator compares live DB to target using `pg-schema-diff` or equivalent.
+3. `dry-run` prints planned DDL and hazards.
+4. `migrate` applies the plan.
+
+### Safe Schema Changes
+
+- Add nullable columns first, cheap defaults only when safe for table size.
+- Add new tables empty. Add indexes for known access patterns.
+- Avoid renames, drops, type rewrites in same release as consuming code.
+- Multi-release: expand-contract sequencing.
+
+## The persistence boundary
+
+Take the clean break between the core and the store from a narrow, domain-named port plus real-DB tests — never from a generic repository. Idiomatically in Go:
+
+- **Declare the interface where it is consumed, and keep it small.** The service that needs persistence declares an interface naming only the operations it calls (`type OrderStore interface { ByID(ctx, id) (*Order, error); Save(ctx, *Order) error }`), in the domain's language. The Postgres implementation (over `sqlc`/`pgx`) lives in its own package, returns concrete domain structs, and is wired in at the composition root. *"The bigger the interface, the weaker the abstraction"* — never expose the store's full CRUD surface.
+- **No generic `Repository[T]`.** Per-entity queries, SQL, and row mapping differ, so persistence belongs to an interface, not a type parameter — Go's own guidance uses a type parameter only to *relate* multiple values, not when the implementation differs per type. A generic base used only by tests is speculative generality; delete it.
+- **Right-size it.** A thin CRUD endpoint does not need a hand-written port over the query layer — reach for one when a rich aggregate with invariants must stay storage-ignorant, and then it is one port per aggregate root. When query variety grows, add a query/specification type, not more methods.
+- Integration-test the adapter against a real Postgres (see `testing.md`); do not mock it.
+
+## Anti-Patterns
+
+- JSONB-everything. Indexes "just in case." Migrations that lock hot tables.
+- Raw string interpolation. A second database without documented need.
+- A generic `Repository[T]` over the query layer, or an exposed store-shaped CRUD surface — premature generality that leaks the schema into the core.

package/src/engineer-skills/groundwork-go-engineer/references/reliability-performance.md

@@ -0,0 +1,105 @@
+# Reliability
+
+## Core Principles
+
+### 1. SLOs, Not Uptime Percentages
+
+Every significant service defines a Service Level Objective — a per-endpoint or per-user-journey target with latency and success-rate components, measured over a rolling window. "99.9% uptime" is not an SLO; "p95 `POST /entities` < 300ms over 30 days, 99.5% success" is.
+
+### 2. Error Budgets Govern Velocity
+
+The budget implied by the SLO is a spendable resource. Teams spending below budget ship riskier changes. Teams above budget pause feature work and pay down reliability debt.
+
+### 3. Graceful Degradation Is a Design, Not a Hope
+
+Every user-facing feature has a defined behaviour when its downstream fails. Degradation is decided at design time and implemented alongside the happy path.
+
+### 4. Timeouts, Retries, and Circuit Breakers Are Defaults
+
+Every outbound call has a timeout. Every retry has a bounded policy with jitter. Every client has a circuit breaker against its most important downstreams. Defaults are set in a shared library; opting out requires a written reason.
+
+### 5. Isolate Blast Radius
+
+A single tenant, user, or noisy consumer must not degrade the experience for everyone else. Isolate by quota (per-tenant rate limits), by resource (dedicated queues), and by bulkhead (separate worker pools).
+
+### 6. Rehearse Failure
+
+Inject failures routinely — killed pods, degraded networks, slow databases. Every chaos experiment that finds something surprising is worth a year of CI.
+
+### 7. Alerts Fire on User Impact, Not Mechanism
+
+Alert when users are affected — SLO burn rate, error-rate spikes on user journeys — not when a server has 80% CPU.
+
+### 8. Every Incident Teaches a Specific Lesson
+
+Post-incident: blameless postmortem, specific reliability assumption invalidated, specific change proposed. No "be more careful" action items.
+
+## Anti-Patterns
+
+- **"99.999% uptime" as a target.** Five-nines for a non-core service is reckless.
+- **Retries without policies.** Retry-forever is a self-inflicted DDoS.
+- **Mechanism alerts.** Paging on CPU without user-impact signal.
+- **Postmortems that blame humans.** The action item is the system fix.
+- **SLOs nobody tracks.** An SLO without a dashboard and burn-rate alert is theatre.
+
+---
+
+# Performance
+
+## Core Principles
+
+### 1. Latency Is a Budget, Allocated Top-Down
+
+Every user-facing operation starts with a latency budget at the edge. The budget is allocated to downstream hops. Budgeting makes trade-offs explicit.
+
+### 2. Measure Tail Latency, Not Average
+
+p50 is a marketing number. p95 and p99 are what users experience. Design for the tail.
+
+### 3. Pre-Compute, Cache, and Denormalise Deliberately
+
+Each trades complexity for latency. Each earns its keep with data, not intuition.
+
+### 4. Backpressure Is Designed In
+
+Every producer has a bounded queue and a defined behaviour when the queue fills: shed, coalesce, block.
+
+### 5. Load Shedding Protects the System
+
+When saturated, serve fewer requests well. Shed on clearly-defined criteria using inbound concurrency limits.
+
+```go
+import "golang.org/x/sync/semaphore"
+
+var maxInflight = semaphore.NewWeighted(1000)
+
+func LoadSheddingMiddleware(next http.Handler) http.Handler {
+    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+        if !maxInflight.TryAcquire(1) {
+            http.Error(w, "Service Unavailable", http.StatusServiceUnavailable)
+            return
+        }
+        defer maxInflight.Release(1)
+        next.ServeHTTP(w, r)
+    })
+}
+```
+
+### 6. Hot Paths Have No Allocations to Spare
+
+For the hottest inner loops, write allocation-aware code. Every allocation is a GC pause in waiting.
+
+### 7. Profile Before You Optimise
+
+Every non-trivial optimisation starts with a profile. The "obvious" bottleneck is almost always wrong.
+
+### 8. Budgets Are Enforced in CI
+
+Bundle sizes, handler latencies — measured in CI against committed thresholds. Regressions require a reviewed waiver.
+
+## Anti-Patterns
+
+- **Optimising on hunch.** No profile, no optimisation.
+- **Average-as-metric.** p50 is a lie. Use percentiles.
+- **Unbounded queues.** A queue without a max is a latency bomb.
+- **"We will fix performance later."** If you ship slow, users remember slow.

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

@@ -0,0 +1,139 @@
+# Testing
+
+## Testing Tiers
+
+### Tier 1 — Service Perimeter Tests (Default)
+
+Most tests live here. Start a real Postgres container, run migrations, exercise the handler through `httptest.NewRecorder`, and assert on HTTP responses and database state.
+
+```go
+func TestCreateEntity(t *testing.T) {
+    ctx := context.Background()
+
+    pg, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
+        ContainerRequest: testcontainers.ContainerRequest{
+            Image:        "postgres:16",
+            ExposedPorts: []string{"5432/tcp"},
+            Env: map[string]string{
+                "POSTGRES_PASSWORD": "test",
+                "POSTGRES_DB":       "test_db",
+            },
+            WaitingFor: wait.ForListeningPort("5432/tcp"),
+        },
+        Started: true,
+    })
+    require.NoError(t, err)
+    t.Cleanup(func() { pg.Terminate(ctx) })
+
+    connStr, _ := pg.ConnectionString(ctx, "sslmode=disable")
+    db, err := sql.Open("pgx", connStr)
+    require.NoError(t, err)
+
+    require.NoError(t, migrate.Up(ctx, db))
+
+    handler := buildHandler(db)
+    rec := httptest.NewRecorder()
+    req := httptest.NewRequest(http.MethodPost, "/entities", body(t, createReq))
+    handler.ServeHTTP(rec, req)
+
+    require.Equal(t, http.StatusCreated, rec.Code)
+}
+```
+
+Use `t.Cleanup` for container teardown. Use `require` for fatal assertions; `assert` for non-fatal checks.
+
+### Tier 2 — Unit Tests (Complex Isolated Logic Only)
+
+Write a unit test when:
+
+- The function has complex conditional logic expensive to exercise through HTTP
+- The function is pure (no I/O) with clear inputs/outputs
+- Edge cases would require brittle HTTP request construction
+
+Do not write a unit test because it is faster or easier. A unit test that passes while the integrated system is broken is a false signal.
+
+```go
+func TestScoringLogic(t *testing.T) {
+    cases := []struct {
+        name  string
+        input ScoringInput
+        want  float64
+    }{
+        {"zero input", ScoringInput{}, 0},
+        {"full confidence", ScoringInput{Confidence: 1.0, Length: 100}, 1.0},
+        {"penalises short segments", ScoringInput{Confidence: 1.0, Length: 5}, 0.5},
+    }
+
+    for _, tc := range cases {
+        t.Run(tc.name, func(t *testing.T) {
+            got := Score(tc.input)
+            assert.InDelta(t, tc.want, got, 0.001)
+        })
+    }
+}
+```
+
+### Tier 3 — System Tests (Rare, Explicit)
+
+Full end-to-end tests across multiple live services. Run in a dedicated CI stage, not on every PR. Add one only when no Tier 1 test can reach the integration point.
+
+## Test Structure
+
+### Package Layout
+
+Test files live alongside the code they test. Internal tests use the same package name; black-box tests use the `_test` suffix. Prefer black-box tests for handlers and services.
+
+### Shared Test Helpers
+
+Container setup, database fixtures, request builders live in `internal/testutil/` and are only compiled for tests.
+
+### Test Isolation
+
+Each test creates its own database state. Use a fresh schema per test run, or truncate tables in `t.Cleanup`. Do not share mutable state across tests.
+
+### Parallel Tests
+
+Mark independent tests with `t.Parallel()`. Tests sharing a container must synchronise table state or use separate databases.
+
+## What to Mock
+
+| Dependency | Approach |
+|---|---|
+| Postgres | Real container via Testcontainers |
+| External HTTP APIs | `httptest.NewServer` returning canned responses |
+| LLM / embedding providers | Interface mock with fixed outputs |
+| Pub/Sub | `testcontainers/modules/pubsub` or interface mock |
+| Time | Pass `time.Time` / `func() time.Time` as dependency; no global `time.Now` |
+
+Do not mock the database. Do not mock internal service or repository interfaces. Mocking your own internals tests the mock, not the code.
+
+## Testing Foundations
+
+Tests are risk-weighted assertions about production behaviour — not boxes ticked for coverage.
+
+### Core Principles
+
+1. **Favour service tests over solitary unit tests.** Interesting bugs live at the boundaries — HTTP serialisation, SQL query correctness, event emission.
+2. **Emulate, don't mock.** If a dependency can run in a container, emulate it.
+3. **Observability is a test surface.** Assert that traces are unbroken end-to-end — a missing span is a test failure.
+4. **Name tests by behaviour.** `[Function] should [expected outcome] when [condition]`.
+5. **Risk-based depth.** Score modules with Impact × Complexity × Change-frequency before deciding test depth.
+6. **Tests are part of the change.** A PR without tests is incomplete.
+
+## Anti-Patterns
+
+- **Mocking the database.** Test against a real schema.
+- **Snapshot tests as a default.** Acceptable only for genuinely opaque artefacts.
+- **Coverage-gated CI.** Use as a read-out, never as a gate.
+- **Shared staging environments as test bed.** No hermetic guarantees, no reproducibility.
+- **Magic `time.Sleep` in tests.** Use `eventually` loops with tight timeouts.
+- **One giant test.** Each test case should be independently runnable and independently failing.
+
+## Bet Slice Rollout — the permanent tests a slice owes
+
+When a bet slice's progress tests go green, the slice rolls out permanent coverage before it closes (bet workflow, Delivery step 5). The bet-progress tests prove the capability once and are archived; these stay.
+
+- **Service perimeter test (always).** One Tier 1 test per capability the slice delivered, exercising the real handler against real Postgres — this is the honeycomb wall that survives refactors.
+- **Unit tests (when logic earned them).** Pure-function tests for branching business logic the slice introduced — state machines, pricing rules, parsers. CRUD plumbing does not earn unit tests; the perimeter test already covers it.
+- **Property-based tests (when invariants exist).** A slice that introduced an invariant — serialization round-trips, idempotent handlers, commutative merges — pins it with a property test (`testing/quick` or rapid), because example-based tests sample invariants instead of stating them.
+- **Contract conformance (when the slice changed an API).** The served OpenAPI must match the promoted spec in `docs/architecture/api/<service>/openapi.yaml`; the generated system suite checks this — the slice's job is to keep the spec promotion current, not to hand-write the check.

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

@@ -0,0 +1,11 @@
+# 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/go-microservice/docs/principles/stack/go/index.md | 5404a872df986823ca05107485ec6e22952c25b39882e44ed82316c0044f0973 | 2026-06-19 |
+| src/generators/go-microservice/docs/principles/stack/go/concurrency.md | e63a90b46f85ad63f0e1535f105106b9f30bff58e0270e9dc8d4b8f91951e0ca | 2026-05-26 |
+| src/generators/go-microservice/docs/principles/stack/go/testing.md | 5df1715b9fa10ff50cb3f18348a7a67dbef70cff80d7d77aefef2d6f1dc5da4c | 2026-05-26 |

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

@@ -0,0 +1,107 @@
+---
+name: groundwork-nextjs-engineer
+description: >
+  Implement, review, and refactor Next.js applications using canonical
+  app docs, Next.js App Router boundaries, React Server Components, Server
+  Actions, Zod schemas, accessibility, and the project's visual system. Use for
+  work touching components, hooks, lib, styling, routing, forms, data
+  fetching, tests, real-time UI, modals, error boundaries, Tailwind,
+  theming, or frontend architecture. Make sure to use this skill whenever a
+  user is working on a Next.js codebase, building UI features, fixing
+  frontend bugs, or reviewing React/Next.js code.
+---
+
+# Next.js Engineer
+
+Frontend execution engineer for Next.js applications. This skill guides implementation within the Next.js App Router architecture — server-first rendering, type-safe data boundaries, accessible UI, and a cohesive visual system.
+
+## Operating Contract
+
+1. Locate the architectural layer before editing. Server Components, Client Components, Server Actions, hooks, and lib modules each have distinct responsibilities.
+2. The capability core owns business logic. The web surface is wired to it through typed fetchers and Server Actions at validated data boundaries — never re-implement a rule the core's contract already proves.
+3. Prefer Server Components by default. Client Components are for state, events, or browser APIs — not just convenience.
+4. Route durable frontend policy to the canonical docs (`docs/principles/stack/typescript/frontend.md`) instead of duplicating it in code comments or this skill.
+5. Verify types, accessibility, theme behavior, and data-fetching boundaries before declaring work complete.
+
+## 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.
+
+## Core Pillars
+
+1. **Server-First Rendering** — Server Components are the default. They reduce client bundle size, eliminate waterfall fetches, and keep sensitive logic server-side. Only reach for `"use client"` when the component genuinely needs browser APIs, user interaction state, or event handlers. This boundary decision is the most impactful architectural choice in the app.
+
+2. **Type-Safe Data Boundaries** — Data flows through explicit, validated boundaries. Server Actions use Zod schemas for input validation. API responses are typed end-to-end. Runtime data never crosses a trust boundary without validation. This catches integration bugs at the boundary rather than deep in component trees.
+
+3. **Accessible by Default** — Accessibility is a design constraint, not a post-hoc audit. Semantic HTML, ARIA attributes, keyboard navigation, focus management, color contrast, and screen reader testing are part of every feature, not a separate checklist. Inaccessible UI is a bug.
+
+4. **Cohesive Visual System** — Every visual value is owned by the design system, not this skill. `docs/design-system.md` is the human source of truth; `.groundwork/config/brand-tokens.json` is its machine projection; the generator projects both into `app/brand.css` and the token utilities + surface classes (`.surface-glass/.surface-elevated/.surface-hero`) in `app/globals.css`. Colour, type, spacing, elevation, blur, gradients, surfaces, and motion are consumed through those tokens — read values from the design system, never invent them. A hardcoded literal bypasses the system, fails the token-conformance lint, and is visual debt.
+
+5. **Optimistic, Resilient UI** — Mutations use optimistic updates with proper rollback. Error boundaries catch failures gracefully. Loading states are intentional, not afterthoughts. The UI should feel responsive even when the network isn't.
+
+## How to Use This Skill
+
+Match the user's task to the smallest relevant reference set. Most tasks touch one or two references.
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Architecture & Layers | `references/architecture.md` | Understanding the app's architectural layers, file organization, or module boundaries. |
+| Server Components | `references/server-components.md` | Deciding server vs client boundary, understanding RSC patterns, streaming. |
+| Data Fetching | `references/data-fetching.md` | Fetching data in server components, SWR patterns, cache invalidation. |
+| Mutations & Forms | `references/mutations-and-forms.md` | Server Actions, form validation with Zod, optimistic updates, error handling. |
+| Routing & Navigation | `references/routing-and-navigation.md` | App Router conventions, layouts, parallel routes, intercepting routes, modals. |
+| Error Boundaries | `references/error-boundaries.md` | Error handling UI, fallback components, recovery patterns. |
+| Type System | `references/type-system.md` | TypeScript patterns, Zod schemas, shared types, type narrowing. |
+| Tailwind & Styling | `references/tailwind-and-styling.md` | Tailwind v4 mechanics, consuming projected tokens, theming, dark mode, responsive design. |
+| Visual Language | `references/visual-language.md` | Consuming the design system: colour/type/spacing/elevation/surface technique and the projected token + surface utilities. |
+| UX Principles | `references/ux-principles.md` | Interaction patterns, progressive disclosure, feedback, empty states. |
+| Testing | `references/testing.md` | Component tests, integration tests, accessibility testing, test utilities. |
+| Performance & Deployment | `references/performance-and-deployment.md` | Bundle analysis, lazy loading, image optimization, build configuration. |
+| Documentation | `references/documentation.md` | Component documentation, Storybook patterns, inline docs. |
+
+## Task Routing
+
+- **Data fetching or mutations** → Load `references/data-fetching.md` and `references/mutations-and-forms.md`. Verify the server/client boundary.
+- **UI/design work** → Load `references/visual-language.md` and `references/ux-principles.md`. Check design tokens for colors and spacing.
+- **Routing/modal work** → Load `references/routing-and-navigation.md` and `references/architecture.md`. Check existing route conventions.
+- **Real-time UI** → Load `references/data-fetching.md` for streaming and revalidation patterns and `references/server-components.md` for the streaming boundary.
+- **Form work** → Load `references/mutations-and-forms.md`. Verify Zod schema patterns.
+- **Styling/theming** → Load `references/tailwind-and-styling.md` and `references/visual-language.md`. Check design guide.
+- **Performance issues** → Load `references/performance-and-deployment.md`. Profile before optimizing.
+
+## Safety Gates
+
+- Do not use `useEffect` for data fetching — this is an App Router codebase with server-side data fetching. Verify against current patterns in the codebase before introducing fetch-in-effect.
+- Do not introduce hardcoded visual literals (colour, spacing, type, shadow, blur, gradient). Read values from `docs/design-system.md` / `.groundwork/config/brand-tokens.json` and consume token utilities or surface classes — arbitrary literals fail the token-conformance lint.
+- Do not invent framework versions or API assumptions; verify `package.json`.
+- Do not add `"use client"` to a component without confirming it needs browser APIs or interactive state.
+- Run typecheck, lint, and the app's tests where the toolchain is available; report a tier as skipped-with-reason (never silently green) where it is not.
+
+## Hallucination Controls
+
+Before presenting frontend guidance as factual:
+
+- Check `package.json` for framework versions and available dependencies.
+- Check existing components for naming conventions, file structure, and patterns before proposing new ones.
+- Load `docs/design-system.md` and `.groundwork/config/brand-tokens.json` for colour, type, spacing, elevation, and motion values before any visual work — never recall or invent them.
+- Check the app's route structure before inventing new route paths or layouts.
+- Label any recommendation based on general Next.js knowledge (rather than project-specific patterns) as an inference.
+
+## Output Expectations
+
+- Component changes include the server/client boundary decision and its justification.
+- UI changes reference specific design tokens or explain why a custom value is needed.
+- New features include accessibility considerations (keyboard nav, ARIA, screen reader behavior).
+- Verification steps include specific test commands and visual checks to perform.
+- Recommendations distinguish between project conventions and general React/Next.js practices.
+
+## Antipatterns
+
+Reject these patterns:
+
+- **Client Component by default** — Adding `"use client"` out of habit rather than necessity. Server Components are the default for a reason.
+- **Fetch-in-useEffect** — Client-side data fetching when server-side fetching would eliminate the loading waterfall and reduce bundle size.
+- **Hardcoded visual values** — Magic numbers or literal recipes for colour, spacing, typography, shadow, blur, or gradient that bypass the projected token system.
+- **Untyped form data** — Processing form submissions without Zod validation at the Server Action boundary.
+- **Accessibility bolted on** — Treating a11y as a separate pass instead of building it into the component from the start.
+- **God components** — Components that mix data fetching, business logic, and presentation instead of composing smaller, focused pieces.