Resources · extended guidance

SPEC Library — battle-tested templates

SDD's equivalent of "Extended Guidance": nine reference SPECs covering domains where ambiguity is expensive — auth, payments, GDPR, multi-tenancy, AI. Shipped by npx aiad-sdd init into .aiad/specs-library/, ready to adapt rather than start from a blank page.

Every template is written in strict EARS (rules R1–R7), carries YAML frontmatter (format: EARS, governance:, domain:) and pre-maps the applicable Tier 1 governance agents. Placeholders such as {{title}} and {{parent_intent}} mark exactly what you must fill in from your own Intent.

auth-oidc — OIDC authentication

Domain: OpenID Connect 1.0 sign-in via Authorization Code Flow + PKCE. The SPEC covers flow initiation (state, nonce, S256 code challenge), callback validation, code-to-token exchange, full id_token verification against the IdP's JWKS, server-side session storage (HttpOnly cookies, never tokens in localStorage) and logout. Governance: AIAD-RGPD + AIAD-CRA. Use it whenever you delegate identity to an IdP — the security-critical steps are precisely where home-grown flows go wrong.

billing-stripe-tax — billing with Stripe Tax

Domain: B2C/B2B invoicing with Stripe as PSP and Stripe Tax computing EU VAT under the OSS / IOSS regimes (Directive 2006/112/EC). Governance: AIAD-RGPD (customer fiscal data is personal data) + AIAD-CRA (billing-chain integrity). Use it for any European SaaS selling inside and outside the EU.

gdpr-data-export — right to portability

Domain: GDPR Article 20 (portability) and Article 15 (access): an authenticated export request, asynchronous processing and a structured, machine-readable download. Governance: AIAD-RGPD. Use it the moment your product stores personal data — these rights are not optional.

multi-tenant-saas — tenant isolation

Domain: multi-tenant architecture — N customer organisations sharing infrastructure without ever seeing each other's data. The SPEC forces an explicit choice between the three isolation strategies (shared pool with tenant_id, schema per tenant, database per tenant) and covers per-tenant billing. Governance: AIAD-RGPD (each tenant may be a distinct data controller) + AIAD-CRA + AIAD-AI-ACT (shared AI features must not leak training data across tenants). Use it before writing the first line of a B2B SaaS — isolation is a one-way architectural door.

notifications-multi-channel — email, SMS, push, in-app

Domain: multi-channel notifications with granular opt-in, one-click opt-out and per-channel consent rules (transactional email vs explicit SMS consent under ePrivacy, OS-level + app-level push consent). Governance: AIAD-RGPD + AIAD-CRA (webhook signatures) + AIAD-RGAA (accessible HTML and SMS content). Use it whenever you contact users outside the app.

observability-otel — OpenTelemetry

Domain: traces, metrics and structured logs via the OTel SDK and collector, exportable to any backend. The critical concern: no PII or sensitive data may leak into observability signals, and retention obeys GDPR Article 5.1.e. Governance: AIAD-RGPD + AIAD-RGESN (storage and network cost) + AIAD-CRA. Use it when instrumenting a service — observability pipelines are a classic, silent PII exfiltration path.

payment-pci — card payments, PCI-DSS & PSD2

Domain: card payment flow that never touches the PAN: client-side tokenisation through PSP-hosted components (Stripe Elements, Adyen Components), keeping your scope at PCI-DSS SAQ A, plus PSD2 Strong Customer Authentication with Dynamic Linking on amount and beneficiary. Governance: AIAD-RGPD + AIAD-CRA + AIAD-PSD2 (eu-financial pack). Use it for any checkout — this is the template where EARS strictness pays for itself most directly.

rag-llm — Retrieval-Augmented Generation

Domain: a RAG system answering user questions from a controlled corpus with verifiable citations — controlled chunked indexing, retrieval, LLM synthesis. Governance: AIAD-AI-ACT (it is an AI system), AIAD-RGPD (if personal data enters the corpus) and AIAD-RGESN (energy footprint). Use it for any LLM-backed feature: it operationalises the AI Act × GDPR × eco-design convergence that ad-hoc prompting ignores.

search-elasticsearch — full-text search

Domain: Elasticsearch / OpenSearch with field-level classification of indexed data, the right to erasure propagated to the index (an index keeps copies that survive source deletions), and sobriety settings (shards, refresh interval, retention). Governance: AIAD-RGPD + AIAD-CRA + AIAD-RGESN. Use it whenever you index user content — the forgotten-index GDPR failure mode is the whole point of this template.

How to adapt a template

1. Start with the intent, not the template. Run /sdd intent first — the template supplies the COMMENT, your Intent supplies the POURQUOI. Fill {{parent_intent}} with the resulting INTENT-NNN.
2. Adapt, do not adopt. Replace placeholders, delete requirements that do not apply, and tighten the ones that do to your actual stack and constraints.
3. Re-run the gate. A template is a head start, not a validated SPEC: pass /sdd gate again. Since the templates declare Format : EARS, the linter runs in strict mode — keep it at 0 violations to secure the +1 SQS Testability bonus.