groundwork-method 0.0.1 → 0.10.0

package/src/engineer-skills/groundwork-nextjs-engineer/references/visual-language.md

@@ -0,0 +1,69 @@
+# Visual Language & Surfaces
+
+This reference is about **technique** — how to consume the design system and how the surface layer composes depth. It carries **no fixed palette, type, or surface catalogue**. Every concrete value (colours, type scale, shadow stacks, blur radii, gradients, surface treatments) is a per-app decision that lives in `docs/design-system.md` and is projected from `.groundwork/config/brand-tokens.json` into `app/brand.css` and surfaced through `app/globals.css` as token utilities. Read the design system before any visual work; never invent values here.
+
+## Where the values live
+
+The nextjs-app generator projects the design system's `visual` block into `app/brand.css` (regenerated, never hand-edited). `app/globals.css` maps those values into Tailwind token utilities and surface classes. The chain:
+
+| Layer | Owns | You touch |
+|---|---|---|
+| `docs/design-system.md` | The human source of truth — palette, type, elevation, surfaces, motion, at the depth standard | Read it |
+| `.groundwork/config/brand-tokens.json` `visual` block | The machine projection of those decisions | Read it; never hand-edit |
+| `app/brand.css` (generated) | `--gw-*` values + the shadcn structural vars, light and dark | Never hand-edit |
+| `app/globals.css` | Token-utility mappings (`@theme`) + surface classes | Extend structure only, never bake values |
+| Your components | Consume token utilities and surface classes | Here |
+
+**Consume tokens, never literals.** A raw hex/length/shadow/blur/gradient in a component bypasses the design system and fails the token-conformance lint (`eslint.config.mjs`). If you need a raw value, reference the projected custom property (`var(--gw-shadow-mid)`, or the Tailwind var form `shadow-(--gw-shadow-mid)`) — never a literal recipe.
+
+---
+
+## Colour (OKLCH)
+
+The design system defines colour in OKLCH — perceptually uniform lightness, so a colour at `L=0.7` reads equally bright across hues (unlike HSL). **Hex, RGB, and HSL literals are forbidden in components.**
+
+Consume colour through the projected token utilities — `bg-background`, `text-foreground`, `bg-primary`, `text-muted-foreground`, `border-border`, `bg-destructive`, the `chart-*` roles — all backed by the brand's palette in `brand.css`. The semantic role of each (which hue means success, error, accent) is the design system's call, recorded there; honour it rather than reaching for a generic "green."
+
+**Dynamic opacity** — derive a translucent variant of any token without a new variable, via the relative colour function:
+
+```css
+/* technique, not a value: any projected colour var works */
+background-color: oklch(from var(--background) l c h / 0.72);
+```
+
+This keeps one source of truth per colour while allowing per-surface translucency.
+
+---
+
+## Typography
+
+The design system commits a full type scale (families, and per-role size, line-height, weight, tracking) at `docs/design-system.md`; the per-role micro is projected into `--gw-text-<role>-{size,line,weight,tracking}`. Consume the scale through the project's type utilities or those custom properties. Do not invent ad-hoc font sizes — if content does not fit a role, the layout needs adjustment, not a new size. Where figures must align in columns, use the projected tabular-numerals treatment rather than the proportional default.
+
+---
+
+## Spacing (8pt grid)
+
+The design system's spacing scale derives from an 8px base (4px is the optical sub-grid). Consume it through the spacing-scale utilities (`p-4`, `gap-6`, `px-8`) — arbitrary length values (`p-[12px]`) fail lint. Reserve the 4px sub-grid step for optical alignment (icon centring, badge offsets, hairline adjustments), not general spacing. Related elements sit closer than unrelated ones: internal spacing is always tighter than the gap between groups.
+
+---
+
+## Surface depth — the technique
+
+High-end surfaces read as modelled material, not flat boxes. Four techniques compose that depth. The design system decides the *values*; you apply them through the projected tokens and surface classes.
+
+- **Multi-layer shadow.** A single drop shadow reads flat. Depth comes from stacking several shadows — a tight contact layer, a mid ambient layer, a wide diffuse layer — with alpha tapering as each widens, tinted toward the background rather than pure black. The stacks are projected as `--gw-shadow-low/mid/high` and surfaced as the `shadow-low/mid/high` utilities (theme-aware: the dark theme carries deeper variants).
+- **Backdrop blur.** Translucent surfaces over content need `backdrop-filter: blur(...)` (always paired with the `-webkit-` prefix). Blur radii are projected as `--gw-blur-subtle/standard/heavy` and the `backdrop-blur-*` utilities.
+- **Concentric radii.** When nesting rounded elements, keep curves harmonious: `inner radius = outer radius − padding`. Use the radius tokens (`rounded-lg`, `rounded-xl`), not literal pixel radii.
+- **Ambient gradient.** A barely-perceptible mesh/aurora gradient (opacity well under ~0.15, fading to transparent, layered over a solid fallback) adds warmth to large surfaces. Recipes are projected as gradient tokens; the hero surface composes one.
+
+### Surface utilities
+
+The per-app surface vocabulary — the glass/elevated/hero treatments that used to be a fixed catalogue — is projected from the design system's `surface` tokens into composite classes in `globals.css`. Apply them; do not re-author the recipe:
+
+| Class | For | Composes |
+|---|---|---|
+| `.surface-glass` | Regular content cards, panels, list items | standard blur + glass tint + hairline border + `shadow-mid` |
+| `.surface-elevated` | Modals, dialogs, command palette, popovers | heavy blur + denser tint + border + `shadow-high` |
+| `.surface-hero` | Dashboard hero metric, key insight, primary KPI | standard blur + hero tint + ambient gradient + `shadow-high` |
+
+Need a surface the project has not defined? Compose it from the same tokens (`var(--gw-shadow-*)`, `var(--gw-blur-*)`, the palette vars) or add the treatment to the design system and regenerate — never hardcode a one-off stack in a component.

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

@@ -0,0 +1,9 @@
+# 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/nextjs-app/docs/principles/stack/typescript/frontend.md | 98232d067ad03c08d6c1ca5f2caec30e7c3400da55c3afb7754482bc121d7554 | 2026-05-26 |

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

@@ -0,0 +1,196 @@
+---
+name: groundwork-python-engineer
+description: >
+  Implement and review Python service changes using self-contained engineering
+  references and the current repository as the source of truth. Use for Python
+  backend handlers, services, providers, domain models, ML pipelines, FastAPI
+  routes, async patterns, dependency injection, tests, resilience, or service
+  architecture. This skill is the execution router for Python 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 Python service directory or asks about
+  Python backend / ML engineering, even if they do not explicitly ask for a
+  "python engineer."
+---
+
+# Python Engineer
+
+Python 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 Python implementation or review work:
+
+| Check | Why |
+|---|---|
+| Service package layout and nearby examples for the touched layer | Prevents inventing structure that already has a convention |
+| `pyproject.toml` for Python version and dependencies | Avoids version-specific advice that contradicts the project |
+| OpenAPI spec (if HTTP behavior changes) | HTTP contracts are generated — code must match the spec |
+| Pydantic models for domain and request/response types | Boundary validation is the code; must not be duplicated |
+| Event specs (AsyncAPI, Protobuf) for async 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` |
+| Async, event loop, TaskGroup, lifespan, background tasks | `async-patterns.md` |
+| Layer placement, new boundary, dependency direction | `architecture.md` |
+| FastAPI endpoint, route handler, inbound defenses | `architecture.md`, `api-standards.md` |
+| Idempotency, pagination, CORS, load shedding | `api-standards.md` |
+| Database schemas, migrations, test isolation, DB sessions | `database.md` |
+| ML pipeline, inference, embedding, RAG, streaming | `ml-pipelines.md` |
+| ML systems architecture, model serving, evals, prompts | `ml-systems-ai-engineering.md` |
+| AI engineering, context design, agent architecture | `ml-systems-ai-engineering.md` |
+| MCP server, tool/resource design, agent interfaces | `documentation-mcp.md` |
+| Resilience — timeouts, retries, circuit breakers, health probes | `resilience.md` |
+| Graceful shutdown, degradation, lifespan management | `resilience.md`, `async-patterns.md` |
+| Observability — tracing, structured logging, metrics | `observability.md` |
+| Tests, quality gates, coverage strategy, fixture design | `testing.md` |
+| Code documentation, docstrings, Pydantic Field docs | `documentation-mcp.md` |
+| Error handling, exception hierarchy, domain errors | `implementation-patterns.md` |
+| Dependency injection, Protocol ports, wiring | `implementation-patterns.md`, `architecture.md`, `database.md` |
+| Capability port + provider (LLM etc.), generated adapter shape, bare-port bet, `add-capability` | `capability-ports.md`, `architecture.md` |
+
+---
+
+## Skill Handoffs
+
+Use the smallest collaborating set. Keep the Python engineer as lead when the work is mainly Python implementation inside a service directory.
+
+| Condition | Hand off to |
+|---|---|
+| Endpoint shape, OpenAPI, error envelope, pagination, idempotency | API architect / API design skill |
+| Schema, migrations, indexes, query plans, vector search | Database / Postgres design skill |
+| Streaming, Pub/Sub, WebSockets, event schemas, fan-out | Real-time / event architecture skill |
+| Test strategy, CI quality gates, contract tests, flake reduction | Test architecture skill |
+| Deployment, Cloud Run, Docker, CI/CD, observability infra | Platform engineering skill |
+| Go backend coordination, inter-service contracts | Go engineer 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, event contract, ML pipeline, or tests.
+2. **Load minimal routed references** and inspect nearby code before designing.
+3. **State important inferences** when guidance comes from general Python 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
+
+### 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 entrypoints, adapters, or middleware when the architecture expects them in service code.
+- Do not leak adapter-specific types across the core/edge boundary. If an SDK response type appears in a core port, the architecture is broken.
+- FastAPI `Depends`, `Request`, `Session` objects never enter the Service or Domain layers.
+- Always use `pydantic-settings` to validate configuration at startup.
+
+### 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 (`allow_origins=["*"]`).
+
+### Error Handling
+- Do not log and re-raise the same error at multiple layers. Wrap errors with domain exceptions at the adapter boundary and handle at the entrypoint.
+- Map SDK errors to domain exception types before retrying.
+
+### Async Discipline
+- Do not block the event loop. Use `asyncio.to_thread` for synchronous operations.
+- Do not use bare `asyncio.create_task`. Use `asyncio.TaskGroup`.
+- Do not initialise async resources at module level. Use FastAPI `lifespan`.
+
+### Contract & Data Integrity
+- Do not change HTTP behavior without checking the OpenAPI source.
+- Do not change Pydantic models that are part of the public API without checking downstream consumers.
+- Do not add or modify event types without updating the corresponding event spec.
+- Do not use manual UP/DOWN migrations; enforce declarative schema management (e.g., `schema.sql` + diffing engine).
+
+### ML Pipeline Integrity
+- Do not trust model outputs without boundary validation (shape, length, content).
+- Do not hardcode confidence thresholds — use configuration.
+- Do not embed one item at a time — batch API calls.
+- Prompts are code. They live in version control and are covered by evals.
+
+### Generation
+- Do not run code generation manually outside documented generation flows.
+
+---
+
+## Quick Reference
+
+### Domain Error Pattern
+
+| Exception | HTTP | Use |
+|---|---|---|
+| `NotFoundError` | 404 | Resource lookup miss |
+| `UnauthorizedError` | 401 | Missing/invalid auth |
+| `ForbiddenError` | 403 | Valid auth, insufficient permission |
+| `ConflictError` | 409 | Duplicate resource |
+| `ValidationError` | 422 | Field-level validation |
+| `TransientInferenceError` | 503 | Retriable provider failure |
+| `PermanentInferenceError` | 400/500 | Non-retriable provider failure |
+
+### Test Strategy
+
+| Tier | What | Infrastructure |
+|---|---|---|
+| Service test (default) | HTTP → Service → Adapter | Testcontainers + `dependency_overrides` |
+| Unit test (reserved) | Complex domain logic | None |
+| System test (minimal) | Bootstrap + golden path | Full live stack |
+
+### Dependency Injection
+
+```python
+# Port — in src/<package>/core/ports.py
+class Processor(Protocol):
+    async def process(self, uri: str) -> Result: ...
+
+# Adapter — in src/<package>/adapters/
+class ConcreteProcessor:
+    async def process(self, uri: str) -> Result: ...
+
+# Wiring — in entrypoints/ or dependencies.py, typed as the port
+def get_service() -> ProcessingService:
+    return ProcessingService(processor=ConcreteProcessor())
+```
+
+---
+
+## Output Expectations
+
+- Name the references or source files that informed non-obvious decisions.
+- Separate verified repository facts from recommendations based on general Python 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-python-engineer/references/api-standards.md

@@ -0,0 +1,88 @@
+# API Standards & Inbound Defenses
+
+Every Python service must expose a hardened, predictable API surface. Implement these Day-2 operational requirements at the FastAPI entrypoint layer.
+
+## 1. Idempotency
+
+Mutating endpoints (`POST`, `PATCH`) must be idempotent to allow safe client retries; `PUT` is idempotent by HTTP semantics and needs no key.
+
+- Require an `Idempotency-Key` header on mutating requests.
+- Intercept the key in middleware or a FastAPI dependency before business logic executes.
+- Store the intent and the final response in a fast, persistent store (e.g., Redis).
+- If a request arrives with a known key and is `IN_PROGRESS`, return `409 Conflict`.
+- If a request arrives with a known key and is `COMPLETED`, return the cached response immediately.
+
+```python
+from fastapi import Header, Depends
+
+async def verify_idempotency(
+    idempotency_key: str = Header(..., min_length=16)
+):
+    # Check Redis/DB. If completed, raise a custom exception that 
+    # an exception handler catches to return the cached response.
+    pass
+
+@router.post("/items")
+async def create_item(
+    body: ItemCreate,
+    _: None = Depends(verify_idempotency)
+) -> ItemResponse:
+    # Business logic executes only once per key
+    pass
+```
+
+## 2. Cursor-Based Pagination
+
+Never use offset/limit pagination for collections. Offset pagination scales poorly (O(N) database scans) and skips/duplicates items if the underlying dataset changes during iteration.
+
+- Always return a `cursor` (usually a base64-encoded string representing the last seen ID and sort column).
+- Include `has_next` boolean.
+- Use generic Pydantic wrappers for paginated responses.
+
+```python
+from typing import Generic, TypeVar
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+class PaginatedList(BaseModel, Generic[T]):
+    items: list[T]
+    next_cursor: str | None
+    has_next: bool
+
+@router.get("/items")
+async def list_items(cursor: str | None = None, limit: int = 50) -> PaginatedList[ItemResponse]:
+    # Pass cursor down to the repository port
+    pass
+```
+
+## 3. Load Shedding & Concurrency Limits
+
+Do not allow an API to queue requests indefinitely until memory is exhausted or timeouts cascade.
+
+- Implement an inbound concurrency limit (e.g., using a FastAPI middleware that acquires an `asyncio.Semaphore`).
+- When the semaphore is exhausted, immediately shed load by returning `503 Service Unavailable`.
+- This ensures the service remains responsive for health checks and active requests, rather than becoming a black hole.
+
+## 4. CORS Configuration
+
+Configure `CORSMiddleware` explicitly. Never use `allow_origins=["*"]` in production.
+
+```python
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.CORS_ALLOWED_ORIGINS,  # Loaded from env
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PATCH", "DELETE"],
+    allow_headers=["Authorization", "Content-Type", "Idempotency-Key"],
+)
+```
+
+## Anti-Patterns
+
+- **Offset pagination.** `?limit=50&offset=1000` requires the database to scan and discard 1,000 rows.
+- **Ignoring idempotency keys.** Clients will retry on timeouts, causing duplicate side effects (e.g., double charges, duplicate records).
+- **Queuing without bounds.** A service processing 10 req/sec should reject the 100th concurrent request rather than queuing it for 10 seconds.
+- **Wildcard CORS.** Leaks cross-origin data. Always restrict to known frontends.

package/src/engineer-skills/groundwork-python-engineer/references/architecture.md

@@ -0,0 +1,57 @@
+# A Pure Core, Swappable Edges (Python)
+
+## Dependency Rule
+
+Dependencies flow inward. The core never imports from the edge. `import-linter` (a `[tool.importlinter]` contract in `pyproject.toml`) makes this a real gate: it forbids `<package>.core` (and `<package>.core.*`) from importing `<package>.adapters`, `<package>.entrypoints`, `fastapi`, or `sqlalchemy`, and a `<package>.core` → `<package>.adapters` import fails `lint-imports`.
+
+## Where code lives
+
+`src/` holds the importable package `src/<package>/` (src-layout); `<package>` is the service name in snake_case. The pieces (paths relative to `src/<package>/`):
+
+| Zone | Location | Depends on | Contains |
+|---|---|---|---|
+| **Domain** | `src/<package>/core/domain` | Nothing (stdlib + Pydantic only) | Pydantic/dataclass entities, value objects, exceptions, constants |
+| **Ports** | `src/<package>/core/ports.py` (+ per-capability modules like `src/<package>/core/llm.py`) | Domain only | `typing.Protocol` (default) or `abc.ABC` definitions describing the capabilities the core consumes |
+| **Services** | `src/<package>/core/service` | Domain + Ports | Use-case orchestration, workflow coordination |
+| **Adapters** | `src/<package>/adapters/` | Domain + Ports | Concrete implementations (Postgres, external APIs, message brokers) |
+| **Entrypoints** | `src/<package>/entrypoints/` | Domain + Services | FastAPI routes, CLI, Pub/Sub consumers, MCP servers |
+
+## Structural Invariants
+
+- The Domain imports no framework, no SDK, no database driver, no HTTP library. Pydantic and stdlib only.
+- Ports define _what_ (e.g., `store`, `transcribe`), never _how_. Signatures use Domain entities exclusively.
+- Ports use domain names: `publish(msg: Message)`, not `send_to_sqs(msg: Message)`.
+- Services depend on ports (Protocols), not concrete adapters. Return concrete Domain objects.
+- Adapters map external SDK responses into Domain entities. Catch library-specific errors and raise Domain exceptions.
+- Entrypoints validate inputs, map request schemas to Domain objects, and delegate all business decisions to Services.
+- All concrete adapter-to-service wiring happens at the outermost edge (entrypoint startup or a dedicated `dependencies.py` / `container.py`).
+
+## Dependency Injection
+
+- **Constructor injection** via `__init__` for all dependencies.
+- **Explicit lifecycles**: initialise database clients in FastAPI's `lifespan` context manager, not at module level.
+- **No DI frameworks**: wiring is manual, explicit, and visible at the composition root.
+
+## Integrity Testing
+
+### Bootstrap Verification
+A test in `tests/system/test_bootstrap.py` initialises the full dependency tree. Catches missing env vars and wiring failures before production.
+
+### Golden Path System Tests
+Run a live instance against real infrastructure via Testcontainers. Zero mocks. Verify the critical success paths end-to-end.
+
+## Engineering Standards
+
+1. **Pydantic everywhere.** Use Pydantic for all data boundaries (request/response and domain).
+2. **Structured logging.** Use `structlog` or equivalent — never bare `print`.
+3. **Acyclic dependencies.** Import cycles are an immediate signal of leaked layer responsibilities.
+4. **Strict boundaries.** FastAPI `Depends`, `Request`, `Session` objects never enter the Service or Domain layers.
+5. **Clean containers.** Always call `container.stop()` or equivalent in pytest fixtures.
+
+## Anti-Patterns
+
+- **Framework-coupled domain.** If the core imports FastAPI or SQLAlchemy, it is broken.
+- **Leaky ports.** A port with SDK types in its signature is an adapter in disguise.
+- **Anaemic domain models.** Data structs with no behaviour and a thick service.
+- **Over-layering.** Five layers of DTO translation. Adapters are thin.
+- **Layer-skipping.** Entrypoints talking directly to adapters.

package/src/engineer-skills/groundwork-python-engineer/references/async-patterns.md

@@ -0,0 +1,103 @@
+# Async Patterns
+
+## The One Rule: Never Block the Event Loop
+
+Any synchronous call longer than ~1ms inside an `async def` stalls every other coroutine. Symptoms: random, unrelated timeouts across the service.
+
+Blocking calls — file I/O, model loading, `time.sleep`, synchronous SDK methods — must run in a thread:
+
+```python
+import asyncio
+
+result = await asyncio.to_thread(blocking_function, arg1, arg2)
+```
+
+## Structured Concurrency with TaskGroup
+
+`asyncio.TaskGroup` is the only primitive that guarantees all tasks complete — or are cancelled — before control returns to the caller:
+
+```python
+async def process_item(item_id: str) -> ProcessedResult:
+    async with asyncio.TaskGroup() as tg:
+        primary_task = tg.create_task(primary_process(item_id))
+        secondary_task = tg.create_task(secondary_process(item_id))
+
+    return ProcessedResult(
+        primary=primary_task.result(),
+        secondary=secondary_task.result(),
+    )
+```
+
+If either task raises, `TaskGroup` cancels the sibling and re-raises. No orphaned tasks, no leaked resources.
+
+**Never use bare `asyncio.create_task`.** The event loop holds only a weak reference — if the caller exits, the task is garbage collected mid-execution:
+
+```python
+# Wrong — task may be silently dropped
+asyncio.create_task(publish_event(event))
+
+# Correct — task lifetime bound to TaskGroup scope
+async with asyncio.TaskGroup() as tg:
+    tg.create_task(publish_event(event))
+```
+
+## Route Handlers
+
+All route handlers are `async def`. Synchronous `def` handlers are threaded by FastAPI's executor — this makes the async/sync boundary invisible and causes subtle performance issues.
+
+## Background Tasks
+
+Use FastAPI's `BackgroundTasks` for post-response work:
+
+```python
+from fastapi import BackgroundTasks
+
+@router.post("/process")
+async def process_endpoint(
+    request: ProcessRequest,
+    background_tasks: BackgroundTasks,
+) -> ProcessResponse:
+    result = await service.process(request.input_url)
+    background_tasks.add_task(publish_completed_event, result.id)
+    return ProcessResponse.from_domain(result)
+```
+
+## Application Lifespan
+
+Initialise shared resources in the FastAPI `lifespan` context manager:
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    db_pool = await create_db_pool()
+    app.state.db = db_pool
+    yield
+    await db_pool.close()
+
+app = FastAPI(lifespan=lifespan)
+```
+
+**Never initialise clients at module level.** Module-level runs at import time, before env vars load, and cannot be awaited.
+
+## Toolchain
+
+`uv` manages all Python tooling:
+
+```bash
+uv run pytest          # Run tests
+uv add httpx           # Add a dependency
+uv sync                # Sync from lockfile
+```
+
+The lockfile (`uv.lock`) is committed. Every developer and CI run resolves identical trees.
+
+## Anti-Patterns
+
+- **Blocking the event loop.** Use `asyncio.to_thread` for blocking operations.
+- **Bare `asyncio.create_task`.** Creates untracked tasks that can be silently dropped.
+- **Synchronous `def` route handlers.** Write `async def` so the boundary is explicit.
+- **Module-level async initialisation.** `asyncio.run()` at import time conflicts with FastAPI's loop.
+- **`asyncio.sleep` as retry delay.** Use `tenacity` with async backoff.

package/src/engineer-skills/groundwork-python-engineer/references/capability-ports.md

@@ -0,0 +1,44 @@
+# Capability Ports & Providers
+
+GroundWork scaffolds external capabilities (LLM inference, and the same pattern for any future capability) as **a port the core owns plus a selectable provider that satisfies it**. When you read or hand-write one of these, match the generated shape exactly — the generator and your code are the same contract.
+
+## The model
+
+- A **capability** is a port: a `Protocol` the core owns, in `src/<package>/core/` (e.g. `src/<package>/core/llm.py`).
+- A **provider** is the vendor that satisfies the capability; its implementation is the adapter, in `src/<package>/adapters/` (e.g. `src/<package>/adapters/llm.py`). Choosing a provider selects the adapter wired in at the edge; the port and its callers never change.
+- Each provider declares a **footprint** — exactly one of `env`, `compose-service`, `runner`, `none` — which is the only thing that varies the operational cost. Infrastructure is a consequence of the provider, not a default.
+
+| Footprint | Means | Materializes as |
+|---|---|---|
+| `env` | config only (a hosted API) | env vars in `.env.example`, no infra |
+| `compose-service` | a container (a self-hosted server) | a service in `docker-compose.yml` |
+| `runner` | a host process | an entry in `.dev/dev.config.json` runners |
+| `none` | the bare port — a bet | port + stub + conformance test, nothing else |
+
+## Generated shape (LLM reference family)
+
+```
+src/<package>/core/llm.py            # the port — a runtime_checkable Protocol, core-owned
+src/<package>/adapters/llm.py        # the adapter — one provider's implementation
+tests/contracts/test_llm.py   # the contract test
+```
+
+- **Port** — a `@runtime_checkable` `Protocol`, no SDK type in its signature. It lives in its own module (`src/<package>/core/llm.py`), separate from the shared `src/<package>/core/ports.py`, so `add-capability` can generate it independently.
+  ```python
+  @runtime_checkable
+  class TextGenerator(Protocol):
+      async def generate_text(self, prompt: str, max_tokens: int = 100) -> str: ...
+  ```
+- **Adapter** — `LLMClient` in `src/<package>/adapters/llm.py`, implements the protocol structurally (no `class LLMClient(TextGenerator)` inheritance needed). Reads config from `settings`, wraps calls in `tenacity` retry + a circuit breaker, raises the domain's `TransientInferenceError` / `PermanentInferenceError`. A hosted provider adds its SDK to `pyproject.toml`; a self-hosted one uses the OpenAI-compatible client.
+- **Wiring** — provide `LLMClient()` from your composition root (e.g. `dependencies.py get_text_generator`) typed as the `TextGenerator` port from `core.llm`. Never let a service depend on the concrete adapter.
+
+## The `none` bare port (a bet)
+
+`--provider none` ships the port, a stub adapter that raises `NotImplementedError`, and a **strict-xfail** contract test. The test is kept `@pytest.mark.xfail(strict=True)` so a fresh scaffold stays green *and* flips red the moment the adapter starts working — that is the open-bet marker: the contract is fixed, the implementation is owed. Implement the adapter behind the existing port to cash it, then drop the xfail. The conformance check is `issubclass(LLMClient, TextGenerator)` — no construction, no network.
+
+## Rules when you touch one of these
+
+- Add a capability to an existing service with `nx g add-capability --service <svc> --capability llm --provider <p>` — it runs the same injector the scaffold does, idempotently.
+- Swapping providers swaps only the adapter file, its dependency, and the footprint. If a change forces the port or a caller to change, the port was leaky — fix the port, not the callers.
+- Surfaces and frontends do **not** embed an adapter; they call this service's port over its API (keys stay server-side, one owner per capability).
+- A hand-written adapter must pass the same `issubclass(...)` conformance test the generator emits.

package/src/engineer-skills/groundwork-python-engineer/references/database.md

@@ -0,0 +1,88 @@
+# Database & Schema Management
+
+## 1. Declarative Schema
+
+Manual `UP`/`DOWN` migrations (e.g., standard Alembic versions) cause merge conflicts in distributed teams and make the "target state" of the database impossible to read without executing scripts.
+
+We use **declarative schema management**.
+- The source of truth is a single `schema.sql` file (or equivalent Prisma/SQLAlchemy models).
+- We use a diffing engine (e.g., `atlas` or `alembic revision --autogenerate`) to compute the migration dynamically.
+- Migrations are applied automatically during deployment, or generated purely as a verification step in CI.
+
+## 2. Session Management & Dependency Injection
+
+The database session lifecycle is managed at the entrypoint layer (FastAPI), not within the Domain or Service layers.
+
+### The FastAPI Dependency
+
+Use a FastAPI dependency to yield a session and ensure it is closed after the request completes.
+
+```python
+from typing import AsyncGenerator
+from sqlalchemy.ext.asyncio import AsyncSession
+from <package>.adapters.database import async_session_maker
+
+async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
+    async with async_session_maker() as session:
+        yield session
+```
+
+### Injecting into Adapters
+
+Inject the `AsyncSession` into the concrete adapter. **Never pass the session into the Service or Domain layers.**
+
+```python
+from fastapi import Depends
+from <package>.core.ports import OrderRepository
+from <package>.adapters.repository import PostgresOrderRepository
+
+def get_order_repository(
+    session: AsyncSession = Depends(get_db_session)
+) -> OrderRepository:
+    # PostgresOrderRepository implements the OrderRepository port
+    return PostgresOrderRepository(session=session)
+
+def get_order_service(
+    repository: OrderRepository = Depends(get_order_repository)
+) -> OrderService:
+    return OrderService(repository=repository)
+```
+
+The dependency is typed as the **port** (the `OrderRepository` Protocol from `<package>.core.ports`), not the concrete `PostgresOrderRepository` — the seam stays on the port.
+
+## 3. Transaction Boundaries
+
+By default, the `get_db_session` dependency provides an open transaction if the SQLAlchemy engine is configured correctly. However, explicit transaction boundaries (commit/rollback) belong in the Provider or the Service, depending on the isolation requirement.
+
+If the Service coordinates multiple repository calls that must be transactional, use a generic "Unit of Work" (UoW) pattern rather than leaking `session.commit()` into the Service.
+
+## 4. The shape of the persistence port
+
+By default the SQLAlchemy `AsyncSession` already is a unit of work and a collection-like store — a thin CRUD service can use it directly rather than defining its own port. Introduce a persistence port (a domain-named repository Protocol in `src/<package>/core/ports.py`) only when a rich domain aggregate must stay storage-ignorant. When you do:
+
+- **One port per aggregate root, named in the domain's language** (`OrderRepository.get`, `.save`) — never a generic `Repository[T]` / `Generic[T]` CRUD base. Its "generic" is unproven from a single implementation, and a uniform CRUD surface leaks the store's shape into the core (the very leak it was meant to prevent).
+- **Define the port as a narrow `Protocol` or ABC in the core**, exposing only the methods the service calls. A good size check: if an in-memory fake of the port is awkward to write, the port is too broad.
+- When query variety grows, reach for a query object / specification — not more methods on the port or a leaked SQLAlchemy `Select`.
+- Integration-test the adapter against a real Postgres (Testcontainers); never mock the port or the database.
+
+## 5. Test Isolation
+
+Never mock the database. Use Testcontainers for a real Postgres instance.
+Between tests, isolate state by truncating tables rather than recreating the schema, as truncation is significantly faster.
+
+```python
+import pytest
+from sqlalchemy import text
+
+@pytest.fixture(autouse=True)
+async def clear_database(db_session: AsyncSession):
+    """Truncates all tables between tests."""
+    await db_session.execute(text("TRUNCATE TABLE orders, users CASCADE;"))
+    await db_session.commit()
+```
+
+## Anti-Patterns
+
+- **Leaking sessions.** Passing `AsyncSession` directly into the Domain or Service layer breaks the Dependency Inversion Principle.
+- **Manual migration scripts.** Writing manual `ALTER TABLE` statements causes drift. Use a declarative engine.
+- **Mocking the database.** Use Testcontainers. Mocks hide SQL syntax errors and constraint violations.