groundwork-method 0.0.1 → 0.11.0

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

@@ -0,0 +1,126 @@
+# Resilience
+
+## Timeouts
+
+Set explicit timeouts on every outbound HTTP call:
+
+```python
+import httpx
+
+client = httpx.AsyncClient(
+    timeout=httpx.Timeout(
+        connect=5.0,   # TCP connection
+        read=30.0,     # Full response body
+        write=10.0,    # Request body
+        pool=5.0,      # Connection from pool
+    )
+)
+```
+
+Own the timeout at the provider level. The `read` timeout is critical for ML/API providers — a streaming response that hangs mid-way waits indefinitely without it.
+
+## Retries
+
+Use `tenacity` for retry logic:
+
+```python
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential_jitter,
+)
+
+@retry(
+    retry=retry_if_exception_type(TransientError),
+    wait=wait_exponential_jitter(initial=1, max=30),
+    stop=stop_after_attempt(3),
+)
+async def _call_with_retry(self, payload: dict) -> dict:
+    return await self._client.post(payload)
+```
+
+**Jitter is not optional.** Backoff without jitter causes thundering herd.
+
+**Only retry transient errors.** A `400` is permanent — retrying wastes budget. Map errors to domain types before retrying.
+
+## Circuit Breakers
+
+Prevent cascading failure from a down dependency:
+
+```python
+from circuitbreaker import circuit
+
+@circuit(
+    failure_threshold=5,
+    recovery_timeout=30,
+    expected_exception=TransientError,
+)
+async def complete(self, prompt: str) -> str:
+    return await self._client.complete(prompt)
+```
+
+**Set `expected_exception` explicitly.** A breaker that trips on all exceptions produces false opens.
+
+## Graceful Shutdown
+
+FastAPI + Uvicorn handle `SIGTERM` correctly when `lifespan` is used:
+
+1. `SIGTERM` received
+2. Stop accepting new connections
+3. In-flight requests and `BackgroundTasks` complete
+4. `lifespan` cleanup runs
+5. Process exits
+
+Keep the shutdown path fast:
+
+```python
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    resources = await initialise_resources()
+    yield
+    await asyncio.wait_for(resources.close(), timeout=4.0)
+```
+
+## Health Probes
+
+**`/healthz` (liveness):** Returns `200` unconditionally. No external dependency checks.
+
+**`/readyz` (readiness):** Returns `200` only after startup completes. Returns `503` during startup and shutdown.
+
+```python
+@router.get("/healthz")
+async def liveness() -> dict:
+    return {"status": "ok"}
+
+@router.get("/readyz")
+async def readiness(state: AppState = Depends(get_app_state)) -> dict:
+    if not state.ready:
+        raise HTTPException(status_code=503, detail="not ready")
+    return {"status": "ready"}
+```
+
+## Graceful Degradation
+
+Return partial results rather than hard errors when non-critical steps fail:
+
+```python
+async def process_with_enrichment(self, input_uri: str) -> Result:
+    base = await self.processor.process(input_uri)
+    try:
+        enrichment = await self.enricher.enrich(base)
+        return base.with_enrichment(enrichment)
+    except EnrichmentUnavailableError:
+        logger.warning("enrichment.unavailable", item_id=base.id)
+        return base
+```
+
+Log every degraded response with structured context. Silent degradation is invisible in production.
+
+## Anti-Patterns
+
+- **No timeout on provider calls.** Hung connections hold indefinitely.
+- **Retrying non-transient errors.** A `400` never succeeds on retry.
+- **Circuit breaker on all exceptions.** False opens from caller errors.
+- **Long-running lifespan shutdown.** Force-killed by orchestrator.
+- **Silent degradation.** Partial results without structured logs.

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

@@ -0,0 +1,148 @@
+# Security
+
+This service is a trust boundary. Everything outside it — clients, webhooks, queue events, upstream APIs, model output — is hostile until validated. This file is the Python idiom of the framework security canon (`docs/principles/quality/security.md`); when this file and the canon disagree, the canon wins and this file is the one to fix.
+
+The controls below are enforced at the FastAPI entrypoint and the adapter edge, not scattered through the Domain. The boundary is validated once and explicitly; inside it, the core trusts its own types.
+
+## 1. Input is hostile; validate at the boundary
+
+Every inbound payload is a Pydantic model parsed at the route, not a `dict` read field-by-field. Pydantic v2 validation *is* the boundary check — a request that fails parsing never reaches a service.
+
+```python
+from pydantic import BaseModel, Field, EmailStr
+
+class CreateOrderRequest(BaseModel):
+    model_config = {"extra": "forbid"}  # reject unknown fields, never silently drop
+
+    customer_email: EmailStr
+    quantity: int = Field(gt=0, le=1000)
+    note: str = Field(default="", max_length=2000)
+
+@router.post("/orders")
+async def create_order(body: CreateOrderRequest) -> OrderResponse:
+    # body is validated; the service receives a typed domain request, not raw input
+    ...
+```
+
+- `extra="forbid"` turns mass-assignment and typo'd fields into a `422`, not a silent accept.
+- Constrain at the type (`gt`, `le`, `max_length`, `EmailStr`, `Literal`), so the constraint travels with the field and cannot be forgotten by a caller.
+- Do not re-validate between internal callers — the core trusts its own dataclasses (`references/implementation-patterns.md` → Strict Typing). One boundary, scrutinised; no defensive re-checks inside.
+
+## 2. Parameterised queries — never string-built SQL
+
+SQL injection is closed by construction: the query text is constant and every value is a bound parameter. SQLAlchemy and the driver do the binding; an f-string carrying user input into SQL is a defect.
+
+```python
+from sqlalchemy import select, text
+
+# ORM — values are bound, never interpolated
+stmt = select(OrderRow).where(OrderRow.customer_id == customer_id)
+
+# Raw SQL when unavoidable — named bind parameters, never an f-string
+await session.execute(
+    text("SELECT * FROM orders WHERE customer_id = :cid"),
+    {"cid": customer_id},
+)
+```
+
+The session lifecycle and the repository port live in `references/database.md`; security adds one rule on top — no user value reaches a query except as a bound parameter, and table/column names are never taken from input.
+
+## 3. Authorization at the dependency boundary
+
+Authentication establishes *who*; authorization decides *what they may do*. Both are FastAPI dependencies on the route, enforced through one path, not re-implemented per handler.
+
+```python
+from fastapi import Depends, HTTPException, status
+
+async def require_order_access(
+    order_id: str,
+    principal: Principal = Depends(get_principal),  # from the verified token
+) -> str:
+    if not await policy.can_access_order(principal, order_id):
+        raise HTTPException(status.HTTP_403_FORBIDDEN)
+    return order_id
+
+@router.get("/orders/{order_id}")
+async def get_order(order_id: str = Depends(require_order_access)) -> OrderResponse:
+    ...
+```
+
+- The token is verified by a proven provider (OIDC); the service does not hand-roll JWT or session logic. Auth is boring technology — see `docs/principles/system-design/identity-and-access.md`.
+- In a multi-tenant service the tenant is bound to the authenticated principal and enforced at the data boundary, never trusted from a path or query parameter.
+- Least privilege: the database role and any cloud identity the service runs as start minimal and widen only on evidence.
+
+## 4. Secrets are managed, never in code
+
+No secret lives in source, in a committed `.env`, or baked into an image layer. Configuration is validated once at boot with `pydantic-settings` (`references/implementation-patterns.md` → Configuration Validation); secret *values* are injected from the platform's secret manager at runtime.
+
+```python
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+class Secrets(BaseSettings):
+    # Sourced from the secret manager / injected env at runtime — never a default here
+    database_url: str = Field(..., min_length=1)
+    upstream_api_key: str = Field(..., min_length=16)
+
+# .env.example carries names with empty values; real values never enter the repo
+```
+
+The hierarchy is eliminate, then shorten, then rotate: prefer workload identity or OIDC federation (no static credential at all), then short-lived minted secrets, and reserve scheduled rotation for static credentials that genuinely cannot be made ephemeral.
+
+## 5. Supply chain is part of the attack surface
+
+Every third-party package is a potential exploit vector. `uv` pins the full dependency graph in `uv.lock`; CI installs from the lockfile (`uv sync --frozen`), never an unpinned resolve.
+
+- A new dependency is a reviewed decision, not an intuition — check maintenance, ownership, and transitive weight before adding it.
+- Generate an SBOM and run a vulnerability scan (`uv pip audit` / `pip-audit` or equivalent) on every build; a known-vulnerable transitive dependency fails the build.
+- Emit build provenance for anything published, so the artifact's origin is verifiable, not just its contents.
+
+## 6. SSRF on outbound calls
+
+A service that fetches a URL derived from input is an SSRF vector — an attacker aims it at internal metadata endpoints or private hosts. Outbound targets are allowlisted, not reflected from the request.
+
+```python
+from urllib.parse import urlparse
+
+ALLOWED_HOSTS = {"api.partner.example", "cdn.partner.example"}
+
+def assert_allowed(url: str) -> str:
+    host = urlparse(url).hostname
+    if host not in ALLOWED_HOSTS:
+        raise PermanentInferenceError(f"outbound host not allowed: {host}")
+    return url
+```
+
+- Validate the resolved host against an allowlist before the call; reject `file:`, `gopher:`, and non-HTTPS schemes.
+- Set explicit connect/read timeouts on every outbound client so a hostile or slow upstream cannot exhaust the service (`references/resilience.md`).
+
+## 7. Error envelopes that do not leak internals
+
+A client receives a stable, structured error; stack traces, SQL fragments, and upstream provider messages stay in the logs. The Domain raises typed exceptions (`references/implementation-patterns.md` → Error Handling); one exception handler maps them to a safe envelope.
+
+```python
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+@app.exception_handler(AppError)
+async def handle_app_error(request: Request, exc: AppError) -> JSONResponse:
+    logger.exception("request failed", extra={"trace_id": current_trace_id()})
+    # client sees a code and a correlation id — never exc internals
+    return JSONResponse(
+        status_code=422,
+        content={"error": exc.code, "trace_id": current_trace_id()},
+    )
+```
+
+The `422` unification and CORS rules live in `references/api-standards.md`; security's addition is that the body never carries an internal detail and the correlation id is how support traces it without exposing it.
+
+## Anti-Patterns
+
+- **Reading the raw request body as a `dict`.** Bypasses validation; parse a Pydantic model with `extra="forbid"`.
+- **f-string SQL.** `f"WHERE id = {user_id}"` is injection. Bind every value.
+- **Per-handler permission checks that drift.** Authorize through one dependency; model the policy once.
+- **Secrets in `.env`, an image layer, or a default value.** Inject from the secret manager at runtime.
+- **Unpinned installs in CI.** `uv sync --frozen` against `uv.lock`; scan and SBOM every build.
+- **Fetching an input-supplied URL unchecked.** Allowlist the host; block internal addresses and non-HTTPS schemes.
+- **Returning the exception string to the client.** Log the detail, return a code and a trace id.
+- **"It is an internal service, skip auth."** Internal services are an attacker's favourite foothold — zero trust between services.

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

@@ -0,0 +1,216 @@
+# Testing
+
+## The Model: Honeycomb, Not Pyramid
+
+Testcontainers spins up real Postgres/Pub/Sub in seconds. The confidence it provides is categorically different from any mock. Mock-heavy suites pass while production breaks.
+
+**Service tests are the default.** Unit tests are reserved for genuinely complex logic. System tests are minimal.
+
+This is the stack idiom of the framework testing canon (`docs/principles/foundations/testing.md`); when this file and the canon disagree, the canon wins and this file is the one to fix.
+
+Above the honeycomb sits the front-door proof: drive the real running service through the front door a consumer actually calls — its HTTP API — end to end on the real pipeline. Service tests that each pass behind a `dependency_overrides` mock or a stubbed adapter can still assemble into a product that does nothing on the real path, so one proof exercises that path with nothing in the middle faked. This makes a rule on every fake: a stub or fixture standing in for a real stage — an LLM response, a downstream service, a producer's output — is a debt that some test of the real producer must pay. Seeding the input is fine; faking the work in the middle is the violation, and an unpaid debt is a green light wired to nothing.
+
+---
+
+## Tier 1 — Service Tests (Default)
+
+Drive the FastAPI app through HTTP using `httpx.AsyncClient` with `ASGITransport`. Infrastructure runs in containers. Non-containerisable providers (LLM APIs) are replaced at the FastAPI `dependency_overrides` boundary.
+
+### Fixture Setup — App + Async Client
+
+```python
+import pytest
+import httpx
+
+@pytest.fixture(scope="session")
+def app():
+    return create_app()
+
+@pytest.fixture
+async def client(app):
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app),
+        base_url="http://test",
+    ) as c:
+        yield c
+```
+
+### Fixture Setup — Containerised Infrastructure
+
+```python
+from testcontainers.postgres import PostgresContainer
+
+@pytest.fixture(scope="session")
+def postgres():
+    with PostgresContainer("postgres:16-alpine") as container:
+        yield container
+```
+
+Scope containers at `session`. Reset state via transactions or truncation between tests.
+
+### Replacing Non-Containerisable Providers
+
+Replace at the FastAPI boundary, not by patching internals:
+
+```python
+from unittest.mock import AsyncMock
+
+@pytest.fixture
+def fake_processor():
+    proc = AsyncMock()
+    proc.process.return_value = DomainResult(...)
+    return proc
+
+async def test_endpoint_returns_result(client, app, fake_processor):
+    app.dependency_overrides[get_processor] = lambda: fake_processor
+    response = await client.post("/process", json={"input": "test"})
+    assert response.status_code == 200
+```
+
+Route handler, service, and validation all run for real. Only the external API call is substituted.
+
+### Live Provider Tests
+
+Marked `@pytest.mark.live` and selected explicitly with pytest's `-m` flag (excluded from normal runs with `-m "not live"`):
+
+```python
+@pytest.mark.live
+async def test_adapter_against_real_api(processor, fixture_data):
+    result = await processor.process(fixture_data)
+    assert result.confidence > 0
+```
+
+---
+
+## Tier 2 — Unit Tests (Reserved)
+
+Appropriate when logic is genuinely complex, has many branches, operates on pure data, and is painful to exercise through HTTP.
+
+**What earns a unit test:**
+- Domain model immutability, field validation, business rules
+- Complex transformations (resampling, merging, normalisation)
+- Pure algorithms (confidence thresholding, chunking strategies)
+
+**What does NOT earn a unit test:**
+- Service methods that orchestrate adapter calls
+- Endpoint handlers that validate and delegate
+- Adapters that translate SDK responses
+
+```python
+class TestDomainModel:
+    def test_rejects_invalid_confidence(self):
+        with pytest.raises(ValidationError):
+            Segment(text="hello", confidence=1.5, start=0.0, end=1.0)
+
+    def test_is_immutable(self):
+        segment = Segment(text="hello", confidence=0.9, start=0.0, end=1.0)
+        with pytest.raises(ValidationError):
+            segment.text = "goodbye"
+```
+
+---
+
+## Tier 3 — System Tests (Minimal)
+
+**Bootstrap test** — verifies the DI container initialises:
+
+```python
+def test_application_starts():
+    app = create_app()
+    assert app is not None
+```
+
+**Golden path test** — one per critical journey, against the full live stack.
+
+---
+
+## Async Configuration
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+```
+
+Write `async def` tests directly. No `@pytest.mark.asyncio` needed.
+
+## Test Isolation
+
+- **Transaction rollback** per test, or **truncation fixture**.
+- Always reset `dependency_overrides` after each test:
+
+```python
+@pytest.fixture(autouse=True)
+def reset_overrides(app):
+    yield
+    app.dependency_overrides.clear()
+```
+
+## Naming
+
+```python
+# Good
+async def test_process_returns_422_when_input_missing(client): ...
+# Bad
+async def test_process_success(client): ...
+```
+
+## Running Tests
+
+```bash
+uv run pytest tests/unit                        # No infrastructure
+uv run pytest tests/integration -m "not live"   # Requires Docker; skips live APIs
+uv run pytest tests/integration -m live         # Live API tests — requires real keys
+uv run pytest tests/system                      # Bootstrap + golden path
+```
+
+## Trace Assertions
+
+Observability is a test surface: a critical-path request must emit an unbroken trace, and a missing span is a test failure, not an instrumentation TODO. The mechanism is an **in-memory span exporter** from the OTel SDK — no external tooling, and the durable approach now that the dedicated trace-test tools have gone dormant.
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+@pytest.fixture
+def spans():
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    trace.set_tracer_provider(provider)
+    return exporter
+
+async def test_process_emits_trace(client, spans):
+    await client.post("/process", json={"input": "test"})
+    names = {s.name for s in spans.get_finished_spans()}
+    assert "POST /process" in names   # the entry span exists
+    assert "db.insert" in names        # the work span exists
+    # assert the work span is a descendant of the entry span — the trace is connected
+```
+
+Assert what the contract promises — the spans that must exist on the journey, that the trace stays connected across hops, and the attributes a dashboard or SLO query depends on. Pinning the exact span tree and every attribute couples the test to implementation and trains the team to delete it.
+
+## Mutation Testing — the assertion-quality read-out
+
+A fat service test drives many branches through one HTTP call and can *execute* them all while only asserting on the response body. Mutation testing is the one instrument that proves the suite checks what it runs: inject a fault, confirm a test fails, and a surviving mutant is a line you cover but do not check. Treat it as a **signal, never a gate** — run it on the high-risk modules the risk matrix flags and on changed code only.
+
+Use `mutmut` or `cosmic-ray`. A gotcha: `mutmut` 3 no longer mutates module-level code (only function bodies), so a module whose risk lives in top-level constants or table definitions needs `cosmic-ray` or `mutmut` 2. Scope a run to the dense package under change (`mutmut run --paths-to-mutate src/<pkg>/pricing`), read it as a read-out, and turn each surviving mutant on changed high-risk code into the missing assertion — the same read-out catches AI-generated tests whose oracle was lifted from the implementation.
+
+## Anti-Patterns
+
+- **Mocking the interior.** Test what comes out, not which methods were called.
+- **Testing delegation.** `assert adapter.called_once_with(...)` tests the mock, not the code.
+- **Fixture factories that mirror domain.** Construct only what the test needs.
+- **`scope="session"` on mutable state.** Containers: safe. Application state: not.
+- **Skipping the async client.** `TestClient` hides async behaviour. Use `httpx.AsyncClient`.
+
+## Bet Slice Rollout — the permanent tests a slice owes
+
+When a bet slice's progress tests go green, the slice-worker rolls out permanent coverage as part of the same slice, before the driver reviews it (bet workflow, Delivery). The bet-progress tests prove the capability once and are archived; these stay.
+
+- **Service perimeter test (always).** One test per capability the slice delivered, through `httpx.AsyncClient` against the real app with a real database — the coverage that survives refactors.
+- **Unit tests (when logic earned them).** Pure-function tests for branching business logic the slice introduced — validation rules, transformations, state machines. Plumbing does not earn unit tests; the perimeter test already covers it.
+- **Property-based tests (when invariants exist).** A slice that introduced an invariant — round-trip serialization, idempotent consumers, order-independent merges — pins it with Hypothesis, because example-based tests sample invariants instead of stating them.
+- **Critical-path trace assertions (when the slice added an observable path).** A slice that introduced an endpoint or worker whose trace a dashboard or SLO depends on pins it with an in-memory-exporter test: the entry and work spans exist and the trace stays connected. A missing span is a test failure, not an instrumentation TODO.
+- **Contract conformance (when the slice changed an API).** FastAPI's served `/openapi.json` 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.

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

@@ -0,0 +1,20 @@
+# Sync Anchor
+
+This file pins the principle files this skill embeds — both the per-stack Python
+idiom docs and the cross-cutting central canon this skill distils. When any
+listed file changes, this skill must be reviewed in the same commit (and the
+matching per-stack idiom doc reconciled to the canon). CI verifies the hashes
+match.
+
+| Principle file | SHA-256 | Last reviewed |
+|---|---|---|
+| src/generators/python-microservice/docs/principles/stack/python/async.md | 6fdd399fb3052381020ff6e792a724d72bdabe674817794093853cbf24fa9f97 | 2026-05-26 |
+| src/generators/python-microservice/docs/principles/stack/python/resilience.md | d5a7b8f089acdb71d64c1bd4fc9ce80e6947504b01b0ace695ac5ee66554a1b1 | 2026-06-19 |
+| src/generators/python-microservice/docs/principles/stack/python/testing.md | f15e62c83b659788f8b3e39f560779e892080d6bce73768be093d919f3e6946c | 2026-06-26 |
+| src/generators/python-microservice/docs/principles/stack/python/documentation.md | ac58228ba22435bf9bad2ea5bf924bdf9e3674e9967515d5c82aaf3b7825214d | 2026-05-26 |
+| src/generators/python-microservice/docs/principles/stack/python/mcp.md | 1e6deab0b45c7271e0038e9b3d51bc30cb2917488f608e847d566739ac6caeba | 2026-06-19 |
+| src/docs/principles/foundations/testing.md | 205ac40d4c643e7b61cf1e4295df8a7b8b46dcd7c81b857aa8c642ea353f62ef | 2026-06-27 |
+| src/docs/principles/quality/observability.md | 8aa60e213ba03e989c93263153e3a1ac10b2336f6d0360c394f473660d565a0b | 2026-06-26 |
+| src/docs/principles/quality/security.md | 61157d97677142737ec537954dc5aaad7a04012cc8a3dcc855e2d324287fdc64 | 2026-06-26 |
+| src/docs/principles/quality/reliability.md | 9c9788504e0963458667d2727c3fc2359776108be593a2efc6603f6470002252 | 2026-06-26 |
+| src/docs/principles/foundations/documentation.md | 8b576072eaf4970f1251b560781e3e755c864a7920faa599b2834c921cbb8734 | 2026-06-26 |

package/src/generators/add-capability/generator.ts

@@ -0,0 +1,70 @@
+import { formatFiles, Tree } from '@nx/devkit';
+import { recordGeneratorProvenance } from '../shared/provenance';
+import { applyCapability, loadCapability } from '../shared/capabilities';
+
+export interface AddCapabilityGeneratorSchema {
+  service: string;
+  capability: string;
+  provider?: string;
+  stack?: string;
+}
+
+/** Locate the service root in the tree. Accepts a bare name (resolved under
+ *  services/) or an explicit path. */
+function resolveServiceRoot(tree: Tree, service: string): string {
+  const candidates = service.includes('/') ? [service] : [`services/${service}`, service];
+  for (const c of candidates) {
+    if (tree.exists(`${c}/pyproject.toml`) || tree.exists(`${c}/go.mod`) || tree.exists(`${c}/package.json`)) {
+      return c;
+    }
+  }
+  throw new Error(
+    `Could not find service "${service}" (looked for ${candidates.join(', ')} with a pyproject.toml / go.mod / package.json).`,
+  );
+}
+
+/** Infer the stack from the marker file present in the service root. */
+function detectStack(tree: Tree, serviceRoot: string): string {
+  if (tree.exists(`${serviceRoot}/pyproject.toml`)) return 'python';
+  if (tree.exists(`${serviceRoot}/go.mod`)) return 'go';
+  if (tree.exists(`${serviceRoot}/package.json`)) return 'typescript';
+  throw new Error(`Could not detect the stack for ${serviceRoot}.`);
+}
+
+export default async function (tree: Tree, options: AddCapabilityGeneratorSchema) {
+  const capability = options.capability || 'llm';
+  const cap = loadCapability(capability);
+  const provider = options.provider || cap.default;
+  const serviceRoot = resolveServiceRoot(tree, options.service);
+  const stack = options.stack || detectStack(tree, serviceRoot);
+
+  const result = applyCapability(tree, { capability, provider, stack, serviceRoot });
+
+  await formatFiles(tree);
+  recordGeneratorProvenance(tree, 'add-capability', options as unknown as Record<string, unknown>);
+
+  // Guidance — the injector writes the port, adapter, contract test, deps and
+  // env, but composition-root wiring is service-specific and a compose/runner
+  // footprint is workspace-level, so we surface what the engineer must finish.
+  console.log(`\nAdded capability "${capability}" (provider: ${provider}, footprint: ${result.footprint}) to ${serviceRoot}`);
+  console.log(`  port:          ${result.files.port}`);
+  console.log(`  adapter:       ${result.files.adapter}`);
+  console.log(`  contract test: ${result.files.contractTest}`);
+  if (result.wiring) console.log(`  wiring:        ${result.wiring}`);
+  if (provider === 'none') {
+    console.log(`  bet:           the contract test is strict-xfail — implement the adapter to cash it.`);
+  }
+  if (result.footprint === 'compose-service') {
+    console.log(
+      result.materialized
+        ? `  footprint:     injected its container into docker-compose.yml — run \`./dev start\` to boot it.`
+        : `  footprint:     needs a docker-compose service, but no docker-compose.yml was found — run workspace-dev-cli first.`,
+    );
+  } else if (result.footprint === 'runner') {
+    console.log(
+      result.materialized
+        ? `  footprint:     registered as a native runner in .dev/dev.config.json — \`./dev start\` will launch it.`
+        : `  footprint:     runs as a process, but no .dev/dev.config.json was found — run workspace-dev-cli first.`,
+    );
+  }
+}

package/src/generators/add-capability/schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "id": "add-capability",
+  "title": "Add Capability",
+  "description": "Add a capability interface + a chosen provider implementation (or a bare `none` interface) to an existing service. The footprint — env / compose-service / runner / none — follows from the provider.",
+  "type": "object",
+  "properties": {
+    "service": {
+      "type": "string",
+      "description": "The service to add the capability to (directory name under services/, or a path to the service root).",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "Which service should the capability be added to?"
+    },
+    "capability": {
+      "type": "string",
+      "default": "llm",
+      "description": "The capability to add (must exist in the capability registry).",
+      "x-prompt": "Which capability do you want to add?"
+    },
+    "provider": {
+      "type": "string",
+      "description": "The provider that satisfies the capability. Defaults to the capability's default provider. Use `none` for a bare interface (interface + stub + red contract test, to be built as a bet)."
+    },
+    "stack": {
+      "type": "string",
+      "description": "Language stack of the target service. Auto-detected from the service when omitted (e.g. pyproject.toml -> python)."
+    }
+  },
+  "required": ["service"]
+}

package/src/generators/capabilities/llm/capability.json

@@ -0,0 +1,28 @@
+{
+  "id": "llm",
+  "title": "LLM inference",
+  "description": "Text generation via a large language model. The interface is fixed; the provider (and therefore the operational footprint) is a scaffold-time choice.",
+  "default": "anthropic",
+  "providers": ["anthropic", "openai", "local", "ollama", "localai", "none"],
+  "stacks": {
+    "python": {
+      "port": "src/__packageName__/core/llm.py",
+      "portSymbol": "TextGenerator",
+      "adapter": "src/__packageName__/adapters/llm.py",
+      "adapterSymbol": "LLMClient",
+      "contractTest": "tests/contracts/test_llm.py",
+      "envFile": ".env.example",
+      "wiring": "Provide LLMClient() to your composition root (e.g. dependencies.py get_text_generator) typed as the TextGenerator protocol from core.llm, and call generate_text() from your service."
+    },
+    "go": {
+      "port": "internal/core/service/llm.go",
+      "portSymbol": "TextGenerator",
+      "adapter": "internal/llm/llm.go",
+      "adapterSymbol": "Client",
+      "contractTest": "internal/llm/llm_test.go",
+      "envFile": ".env",
+      "module": true,
+      "wiring": "Construct llm.NewClient() in cmd/api/main.go and pass it (typed as the service.TextGenerator interface) into your service. Run `go mod tidy` if a provider added a dependency."
+    }
+  }
+}

package/src/generators/capabilities/llm/providers/anthropic/footprint.json

@@ -0,0 +1,13 @@
+{
+  "kind": "env",
+  "summary": "Anthropic Claude over HTTPS. API key in env; no infrastructure.",
+  "env": [
+    { "name": "LLM_API_KEY", "required": true, "default": "" },
+    { "name": "LLM_BASE_URL", "required": false, "default": "" },
+    { "name": "LLM_MODEL", "required": false, "default": "claude-sonnet-4-6" }
+  ],
+  "stacks": {
+    "python": { "dependencies": ["anthropic>=0.40.0"] },
+    "go": { "dependencies": [] }
+  }
+}